Growing Venture Solutions - GVS - Information Architecture http://growingventuresolutions.com/taxonomy/term/139/0 en Module owners: How to make your module description useful http://growingventuresolutions.com/blog/module-owners-how-make-your-module-description-useful <p>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?</p> <p>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.</p> <h2>Most important elements of Drupal project pages</h2> <p>What are site builders looking for when evaluating a module? I asked Drupallers via Twitter what they look at specifically and got the following:</p> <!--break--><!--break--> <ol> <li>Who the maintainers are. </li><li>Date of last commit. </li><li>How recent the recommended version is. </li><li>Date of last release. </li><li>Number of open issues. </li><li>Number of commits. </li><li>Usage stats. </li><li>Issue follow-up rate. </li><li>What does the module <em>do</em>? </li><li>Why was the module created? </li><li>What problem is the module trying to solve? </li><li>Is the module generic enough to apply to other problems? </li><li>Is there any documentation? </li><li>Will there be a Drupal 7 version soon? </li></ol> <p>Notice that items 1-7 are provided automatically by the Drupal.org <a href="http://drupal.org/project/project">Project module</a>. And items 9-12 are details that <strong>only the module maintainers can provide within the project's Full description field</strong>.</p> <p>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.</p> <p>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...</p> <h2>Useful description idea #1: use subheadings</h2> <p>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?</p> <p>Here's a list of subheadings that would be awesome. I'll describe them fully below.</p> <ul> <li>Overview</li> <li>Features</li> <li>Requirements</li> <li>Known problems</li> <li>Tutorials</li> <li>Pledges</li> <li>Credits</li> <li>Recommended modules</li> <li>Similar projects</li> </ul> <h2>Useful description idea #2: Write a good overview</h2> <p>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).</p> <p>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.</p> <p>It's all about managing expectations!</p> <h2>Useful description idea #3: Summarize features</h2> <p>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 <a href="http://drupal.org/project/filefield">FileField</a> and <a href="http://drupal.org/project/imce">IMCE module</a> do the feature list well.</p> <p><a href="http://growingventuresolutions.com/gvsfiles/imce-desc.png"><img src="http://growingventuresolutions.com/gvsfiles/imce-desc.png" alt="Tell us why your module rocks!" /></a></p> <h2>Useful description idea #4: Include requirements</h2> <p>Include module or library dependencies as well as any other technology requirements, e.g. PHP5. <a href="http://drupal.org/project/filefield">FileField</a> does this. Why? Because like any recipe, it helps to know what ingredients you need upfront, before you're waist-deep!</p> <p><a href="http://growingventuresolutions.com/gvsfiles/filefield-desc.png"><img src="http://growingventuresolutions.com/gvsfiles/filefield-desc.png" alt="Features and requirements spelled out in the admin menu description" /></a></p> <h2>Useful description idea #5: Share known problems</h2> <p>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.</p> <p><a href="http://growingventuresolutions.com/gvsfiles/imce-known.png"><img src="http://growingventuresolutions.com/gvsfiles/imce-known.png" alt="screenshot of IMCE's known issues" /></a></p> <h2>Useful description idea #6: Credit sponsors and maintainers</h2> <p>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.</p> <p>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.</p> <p><a href="http://growingventuresolutions.com/gvsfiles/adminmenu-desc.png"><img src="http://growingventuresolutions.com/gvsfiles/adminmenu-desc.png" alt="Features and requirements spelled out in the admin menu description" /></a></p> <h2>Useful description idea #7: Create and list tutorials</h2> <p>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.</p> <p>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.</p> <h2>Useful description idea #8: Pledges</h2> <p>If you've taken the D7CX, D7AX and any other pledges, list them.</p> <h2>Useful description idea #9: Acknowledge other projects</h2> <p>Yes, the <a href="http://drupal.org/project/pivots">Pivots</a> 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.</p> <p>Likewise, if you're aware of modules similar to yours, feel free to add them or link to a node in the <a href="http://groups.drupal.org/similar-module-review">Similar Module Review group</a> or this issue on the <a href="http://groups.drupal.org/node/20384">myriad Tabs and Slideshow modules</a>.</p> <h2>Oh noes! This description is too long!</h2> <p>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. <a href="http://drupal.org/node/161085">Module documentation guidelines</a> are provided in the Drupal.org handbook.</p> <p>People will love you forever if you provide awesome documentation in the form of screenshots, screencasts and a well-written Documentation node.</p> <h2>What next?</h2> <p>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.</p> <p>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?</p> <p>The end goal is for me to create a Documentation node drupal.org to describe these best practices for module descriptions.</p> <p>Many thanks to <a href="http://www.twitter.com/arianesays">@arianesays</a>, <a href="http://www.twitter.com/decibelplaces">@decibelplaces</a>, <a href="http://www.twitter.com/deviantintegral">@deviantintegral</a>, <a href="http://www.twitter.com/dmitrig01">@dmitrig01</a>, <a href="http://www.twitter.com/joelfarris">@joelfarris</a>, <a href="http://www.twitter.com/jpoesen">@jpoesen</a>, <a href="http://www.twitter.com/stevenmerrill">@stevenmerrill</a>, <a href="http://www.twitter.com/greggles">@greggles</a>, <a href="http://www.twitter.com/ezrabg">@ezrabg</a> and <a href="http://www.twitter.com/benswords">@benswords</a> for contributing to this post via Twitter!</p> <h2>P.S. If this sounds good to you...</h2> <p>Use this handy cut and paste skeleton to flesh out your project description!</p> <p><div class="codeblock"><code>&lt;h2&gt;Overview&lt;/h2&gt;<br /><br />&lt;h2&gt;Features&lt;/h2&gt;<br /><br />&lt;h2&gt;Requirements&lt;/h2&gt;<br /><br />&lt;h2&gt;Known problems&lt;/h2&gt;<br /><br />&lt;h2&gt;Tutorials&lt;/h2&gt;<br /><br />&lt;h2&gt;Pledges&lt;/h2&gt;<br /><br />&lt;h2&gt;Credits&lt;/h2&gt;<br /><br />&lt;h2&gt;Recommended modules&lt;/h2&gt;<br /><br />&lt;h2&gt;Similar projects&lt;/h2&gt;</code></div></p> http://growingventuresolutions.com/blog/module-owners-how-make-your-module-description-useful#comments Planet Drupal Information Architecture Writing for the web Mon, 13 Dec 2010 14:34:09 +0000 lisa 1170 at http://growingventuresolutions.com