GVS is now part of Acquia.
Module owners: How to make your module description useful
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>
- Login to post comments
GVS projects
GVS is now part of Acquia.
Contact Acquia if you are interested in a Drupal Support or help with any products GVS offered such as the Conference Organizing Distribution (COD).
Comments
This should be in Drupal.org!
This should be in Drupal.org! =)
Wouldn't it be awesome if someone could convince the D.O mantainers to fill up new project nodes with your skeleton (probably filled in with some instructions)?
This post should go into a handbook page and the project edit page should show a message linking to it.
Already started on it... see
Already started on it... see http://drupal.org/node/997066 =)
I've found that a screenshot
I've found that a screenshot of both the admin and user-facing interfaces helps out SO much. If you can't do multiple screenshots, just combine two into one.
Totally agree on the
Totally agree on the Screenshot. A picture is worth a thousand words.
Great stuff. If only releases
Great stuff. If only releases would be shown above it all. I'm thankful for well written project pages but 99% of the time I come to click a download link :-)
Awesome.
This is very helpful. I'll be updating my project pages soon. Thanks!
Putting this on drupal.org++.
Updated my projects
I updated my projects to use this:
http://drupal.org/project/admin_menu_dropdown
http://drupal.org/project/toolbar_hide
http://drupal.org/project/admin_menu_profile
Excellent! Looks good!
Excellent! Looks good!
I think there are still many
I think there are still many ways to improve, the suggesting implies text that will span atleast one whole scroll pushing the download links far below the fold. I am not sure that is something we want. We should really reconcider the design of this page when it comes to additional information like pledges, credits, recommended modules etc.
Yes, people will probably
Yes, people will probably have to scroll. But I don't think this is a huge deal since for downloading modules, you normally only need to download once initially, and then to get updates.
The d.o. redesign UI purposely wants to encourage people to explore what Drupal can do, before downloading software and getting frustrated when when their expectations aren't met immediately. The same could be said for contrib modules....
The advanced site builders are probably using Drush (not saying all, but many!) so placement of the download link doesn't matter to them. What does matter is if they need to know what the release numbers are.
That said, the download links could appear elsewhere, but I'm not attempting to redesign the UI of project pages here. I know there are others who wish the release info/download links were higher up on the page. Definitely something to discuss in the issue queue at http://drupal.org/project/issues/project
often i find it helpful to
often i find it helpful to see which related/similar modules there are
TEASERS
If you don't use a proper teaser break, most or all of your project page will be in the overall modules list. IMHO, only the Overview should appear on that page, so you should insert the teaser break manually. That also implies that the overview be the first thing on the page; it's your first opportunity to make a good impression.
You hear this all the time, but few people heed it: spelling and grammar count. If English is not your first language, this can be a major problem. Remember, one of the project page's main purposes is to market your module to potential adopters. Find someone who can edit, or even rewrite, your project page in clear, concise, and proper English.
Great article!!
I will take some notes for my first Drupal module ;)
Thank you very much for the tips.