19.5     Documenting your project

This is NOT the latest copy of this book; click here for the latest version.

Although it is important to spend a lot of your time actually writing your PHP code, it is usually equally important to write documentation for the project - for programmers and also for end-users.

Code documentation should include your original design notes plus any modifications (which in turn should include class and function information), copious amounts of comments in your code where appropriate, as well as, if possible, transcripts of design and development meetings. Comprehensive design notes are crucial to have to hand during development meetings, and also are very helpful when inducting new programmers into a project. Comments in your code should be a given and you are asking for trouble by ignoring them. Finally, the meeting transcripts might sound like an irritating piece of red tape in there, but, yes, it is better to pay the extra cash to get a transcriber on your team than find half-way through a project that no one can remember why feature X was required.

When it comes to end-user documentation this is something you will need to sort out yourself as it is well outside the topic of this book. Having said that, you will find it is best to write much of it yourself, then send it to external documentation writers for rewriting.

Writing documentation of any kind is not much fun for any of us, but it is a chore that needs to be done and is usually worth the effort. The better your code documentation is, the easier the project will be to maintain, and the better your user documentation is, the fewer support calls you will have to handle - at least, that is how the theory goes!