Writing Documentation

Introduction

First of all you need a good documentation of your application to fulfill your custormer's needs. The first thing they are often going to see is not your well written code or or the application in action but a documentation - and we all know that the first impression counts. Besides that, you need a documentation to make your application maintainable. The point is that not just you should be able to fix some bugs or add some new features to the application - everybody should! But working on on somebody else's code without documentation is a pain. (Believe me it is!) So there two types of documentation we need:

• A user manual.
• A technical documentation.

These are two different things! Do not expect your customer to browse your API documentation or a developer to be happy with a manual just explaining the basic concepts. But there is a solution for this problem:

PHPDocumentor

PHPDocumentor is an API documentation tool for PHP. It is part of the project PEAR. It's documentation is very good and available in different formats: http://phpdoc.org/docs/. Its advantage over PHPDoc or similar tools is that tutorials in DocBook format can easyly be included. For DocBook see http://www.docbook.org. The book DocBook published by O'Reilly is available online: http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html. Using PHPDocumentor it is possible to fulfill both your customer's and other developer's needs.

Tutorials may be written as any legal DocBook top-level tag (

<book>, <chapter>, <article>, <refentry>

We will not cover ony more of the usage of PHPDocumentor here! Please see it's documentation. Just one more thing: follow all rules of PHPDocumentor. When generating the documentation no warnings or errors should occurre.

Rule-of-thumb

For each line of code there should be on line of documentation!