Nancy's Web If you don't know where you've been, how do you know where you are?

Documentation

We all know that programmers make terrible documenters; get over it or hire one.

If you've used Drupal for more than a day, you've already encountered poorly documented modules. Many of them are so poorly done that you have no idea what they do or why you might want to use it. Don't let your module fall into that category.

In case you haven't discovered it yet, there is a handbook section< for including the masterpieces of documentation that you're about to create.

Let me first point out that there are actually three, or four, documents that you need to consider:

1. README.txt - This will be included with your module's distribution (tarball). It provides further information to the person who is installing your module. It should include any special instructions or considerations that need to be addressed at installation or configuration time.
2. INSTALL.txt - this is an optional file that can be used if the "readme" file is too large or complex. It would concentrate on the installation tasks.
3. Project page - This is a succinct< description of what your module offers and does. Remember this will probably be your first opportunity to "sell" your module to the potential user. There are many pages on the web on writing good copy, so I will not go into much of that here. If you need to put more stuff on the page than makes a good teaser, you should use a teaser end tag ("<!--break-->"> because this will be listed on the Downloads pages.
4. Handbook page - This should be linked both from and to your project page (there is a "documentation" field there to link to this). Here you may write everything that needs to be said, including the stuff you put into the other pages (yes, even the "readme" and "install" files. I tend to use a basic template to get me started. Supplying a few use cases can help a potential implementor to get a good idea on how the module can be used on his/her site.

Coding Standards

If you recall from the previous article, I recommend that you install and use the Coder module<. In addition to making sure you've adhered to the Drupal coding standards<, this module also can give you performance hints and Drupal version upgrade advice.

If you don't use it, sooner or later, someone is going to "suggest" that you do. If it's webchick, watch out!

Translation

Drupal has a diverse and international community. Many of your potential adopters are not going to speak English or want to have her/his site in English. If your module is valuable to someone with a different language, they may very well step up and provide you with a translation ("po") file. You can help them out by providing them with a translation template ("pot" file) in your distribution.

You can go through the trouble of looking up the template standards and combing through your module looking for translatable strings, or you can do it the easy way: Translation Template Extractor module<. (more here<)

After installing this module, you will need to enable the "locale" core module. This adds a "Localization" entry to your "Administration » Site configuration" menu. On that page, you will find a tab labeled "Extract strings." Simply expand the appropriate fieldset for your module's location and select your module. This will create a file that will be saved to your disk. Locate it and move it into a subdirectory (of your module directory) called "po." Use CVS > Add contents to tell CVS to include this file. Now when you commit your module, this template will be included.