Module owners: How to make your module description useful

lisa — Mon, 13 Dec 2010 14:34:09 +0000

Here's the scenario: Someone semi-familiar with Drupal is building a site. They need to find a module to meet one of the site's requirements. Since there are over 5000 modules for Drupal 6, it must exist, right?

Let's assume they don't know who to ask, so they start researching. To evaluate contributed Drupal modules, the first resource they will use is the module's project node on Drupal.org.

Most important elements of Drupal project pages

What are site builders looking for when evaluating a module? I asked Drupallers via Twitter what they look at specifically and got the following:

Who the maintainers are.
Date of last commit.
How recent the recommended version is.
Date of last release.
Number of open issues.
Number of commits.
Usage stats.
Issue follow-up rate.
What does the module do?
Why was the module created?
What problem is the module trying to solve?
Is the module generic enough to apply to other problems?
Is there any documentation?
Will there be a Drupal 7 version soon?

Notice that items 1-7 are provided automatically by the Drupal.org Project module. And items 9-12 are details that only the module maintainers can provide within the project's Full description field.

The above details tell a site builder about the activeness and awareness of the maintainer(s), whether the module can be considered reputable because of the names of the maintainers behind the module and hopefully, give them enough info to know whether they should use the module.

The folks that responded to my (very non-scientific) survey are all Drupal-savvy. What about the less-than-savvy? The maintainer names won't be meaningful and neither will some of the stats. The emphasis is now on making your module description more useful. Here's a few ideas...

Useful description idea #1: use subheadings

Subheadings make your description more easily scannable. In an ideal world, Drupal module maintainers would adopt a standard for subheading text and sizes. I've seen h2, h3 and strong. Which is the right one?

Here's a list of subheadings that would be awesome. I'll describe them fully below.

Overview
Features
Requirements
Known problems
Tutorials
Pledges
Credits
Recommended modules
Similar projects

Useful description idea #2: Write a good overview

Try to answer the following questions in 5 sentences or less: What does your module do? What's it trying to solve? Who is the module for/who is the audience? This reduces time wasted and also, if you can confidently tell someone this module is for them, they're more likely to use it and support it. And if it's easier to describe with pictures, go for it (see Idea #7).

Greggles likes to include version notices too, e.g. "Version 6.x-2.x dev is not stable and probably won't be for a year or more. It is the home of new experimentation and crazy new features. Version 7.x-1.x-dev is a direct port of the 6.x-2.x-dev and will be the stable version for Drupal 7. There will be no direct port of 6.x-1.x-dev" etc.

It's all about managing expectations!

Useful description idea #3: Summarize features

This should be a bulleted list of features to help people quickly figure out if it's useful to them. Keywords will also be useful when folks are searching. Both FileField and IMCE module do the feature list well.

Useful description idea #4: Include requirements

Include module or library dependencies as well as any other technology requirements, e.g. PHP5. FileField does this. Why? Because like any recipe, it helps to know what ingredients you need upfront, before you're waist-deep!

Useful description idea #5: Share known problems

If there are conflicts, incompatibilities, extremely common bugs, or gotchas that are easy to miss, be upfront about it. Briefly describe the problem, link to the issue (so others can contribute), and you should see a reduction on the number of duplicate issues that are created.

Useful description idea #6: Credit sponsors and maintainers

If any organization in some way sponsored work on the module, link them! It extends credibility, and it furthers the notion that modules can be sponsored. Imagine how great it would be to have more of your module work sponsored (that is, your time is compensated in some way). If organizations see the benefit of sponsoring, in the form of free advertising and community karma, especially as a module's popularity grows, they'll be more inclined to sponsor future projects, and can endorse sponsoring to other companies.

Also, let's not forget co-maintainers. Since "ownership" of modules usually changes over time, co-maintainers names and other history are useful to have recorded here.

Useful description idea #7: Create and list tutorials

In addition to the Documentation link provided by the Project node, a list of blog posts, demos, screencasts, screenshots, reviews, and any other resources should be listed here. Smaller projects probably won't be written up in blog posts, but having a list of the ways one can learn how to use your module is very helpful, especially at a time when they're getting frustrated.

You can help a newbie a ton if you create a short screencast showing the typical usage and configuration. If you're not up for making a screencast, provide embedded (or linked) screenshots of the module configuration and module in action.

Useful description idea #8: Pledges

If you've taken the D7CX, D7AX and any other pledges, list them.

Useful description idea #9: Acknowledge other projects

Yes, the Pivots already lists Related projects, but it's not quite the same as Recommended modules. If your module works particularly well with other modules, list them here.

Likewise, if you're aware of modules similar to yours, feel free to add them or link to a node in the Similar Module Review group or this issue on the myriad Tabs and Slideshow modules.

Oh noes! This description is too long!

Of course, if your project page is too long, you risk overwhelming readers and/or losing their interest. If you have a lot to say, consider linking to your detailed README.txt in addition to creating module documentation. Module documentation guidelines are provided in the Drupal.org handbook.

People will love you forever if you provide awesome documentation in the form of screenshots, screencasts and a well-written Documentation node.

What next?

If you think it's a nice, considerate gesture to not waste people's time by clarifying your module's benefits, requirements and current issues, let us know.

We're interested in hearing what others think. Is this something we can encourage on Drupal.org? What other info and subheadings should be included?

The end goal is for me to create a Documentation node drupal.org to describe these best practices for module descriptions.

Many thanks to @arianesays, @decibelplaces, @deviantintegral, @dmitrig01, @joelfarris, @jpoesen, @stevenmerrill, @greggles, @ezrabg and @benswords for contributing to this post via Twitter!

P.S. If this sounds good to you...

Use this handy cut and paste skeleton to flesh out your project description!

<h2>Overview</h2>

<h2>Features</h2>

<h2>Requirements</h2>

<h2>Known problems</h2>

<h2>Tutorials</h2>

<h2>Pledges</h2>

<h2>Credits</h2>

<h2>Recommended modules</h2>

<h2>Similar projects</h2>

Growing Venture Solutions - GVS - Writing for the web