Documentation

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

If you've used Drupal

Drupal

An open-source content management system that is used on this site and is taking over the world. 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 moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP. 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 moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP.'s distribution (tarball). It provides further information to the person who is installing your moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP.. 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 moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP. offers and does. Remember this will probably be your first opportunity to "sell" your moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP. 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 linkThe technique which points to another page, anywhere on the Internet, from the current page. 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 moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP. can be used on his/her siteA logically grouped set of content - also web 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 moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP. also can give you performance hints and Drupal

Drupal

An open-source content management system that is used on this site and is taking over the world. 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

Drupal

An open-source content management system that is used on this site and is taking over the world. has a diverse and international community. Many of your potential adopters are not going to speak English or want to have her/his siteA logically grouped set of content - also web site. in English. If your moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP. 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 moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP. looking for translatable strings, or you can do it the easy way: Translation Template Extractor module. (more here)

After installing this moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP., you will need to enable the "locale" core moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP.. This adds a "Localization" entry to your "Administration » SiteA logically grouped set of content - also web site. configuration" menu. On that page, you will find a tab labeled "Extract strings." Simply expand the appropriate fieldset for your moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP.'s location and select your moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP.. This will create a file that will be saved to your disk. Locate it and move it into a subdirectory (of your moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP. directory) called "po." Use CVS > Add contents to tell CVS to include this file. Now when you commit your moduleAn add-on, or extension, to Drupal to provide additional functionality; written in PHP., this template will be included.