Why write good documentation for open source code?

Writing good documentation is essential to the success of any software project. The quality of documentation can be even more important than the quality of the code itself, as a good first impression will prompt developers to look further into your code. phpDocumentor is designed to make it easier to create documentation. phpDocumentor even makes it possible to generate separate sets of documentation from the same source!

Writing Great Documentation

Consider the audience

The first question any writer must ask is "Who is my audience?" This will answer many questions. For most software, such as any MS product, the software is intended only to be used. The programmers are the only people who have access to the source code. The challenge in this case is to write good documentation for end-users.

When writing documentation for an open-source project intending to be both used and extended, this challenge is magnified by the fact that many people will also intend to extend the source, or even find obscure bugs and fix them. These two audiences tend to be opposed to each other in their needs.

An end-user generally wants:

• Instruction-style writing, that explains and describes general concepts more than how a particular variable is used

• Interface information only, no low-level details

• Examples of how to use, and tutorials

• Details on how program elements interact, which elements use others

• Where in the source code an action or series of actions occurs

• How to extend the code to add new functionality

These two kinds of users can not be serviced by just API documentation or just tutorials, but a subtle blend of the two.

Using phpDocumentor to make documentation for two separate audiences

In essence, there may need to be two separate sets of documentation! phpDocumentor can be used to create this option using a few things. First, using the command-line file-selection options, one can write two sets of documentation, one for end-users, and the other for programmers, and put them in different subdirectories. For instance, one could put enduser docs in "enduser/tutorials" and programmer docs in "programmer/tutorials." In addition, using the @access tag, one can mark programmer-level elements with @access private, and they will be ignored by default. The @internal tag and inline {@internal}} inline tag construct can be used to mark documentation that is low-level or internal to a smaller audience of developers. When creating programmer documentation, turn on the parse private option (see -pp, --parseprivate), and the low-level detail will be generated.

More important, the in-code documents in your DocBlocks must be written for both end-users and programmers wherever possible.

phpDocumentor uses the chaining feature of tutorials to link together related documentation like chapters in a book, and this is another way to organize documentation. Experiment, and find what's best for your project's needs.

Tips on Revising

There are many ways of creating good documentation, but perhaps the best is to read what you have written from different perspectives. Open up your documentation, and try to use it to figure out your software project. If this is difficult, go back and edit or rewrite. Remove anything that is confusing or unnecessary, make sure everything is there that is needed, and then when it seems good, ask a php user that doesn't know your project, or even a non-programmer to read it and use their reactions to tailor the documentation.

Conclusion

The use of phpDocumentor will definitely improve the look and feel of your documentation, but don't stop there, let it help you to create truly dynamic documents that are easily maintained and kept up-to-date. After all, great docs for great programs will help to secure PHP's rightful throne as the best out there!

References for learning how to use phpDocumentor

• phpDocumentor Quickstart