|
|
|
|
| Tutorial |
Writing Documentation
In addition to commenting and structuring, it’s important to pay attention to documenting.
The documentation for a project is probably the first part of the project that
your customers will see, and the first impression is the one that counts.
Professionally laid out documentation that contains more than the obligatory
“Follow the installation instructions in the README” should be a routine step in
your development process. Just as you expect a well-written manual for your cell
phone, new monitor, or other technical item purchased in even the smallest store,
your customers expect good documentation from you (not to mention that they’re
probably paying you a lot of money for it).
As with comments, extensive documentation is usually produced with the help of
RAD tools. Unfortunately, no tools exist yet that are designed especially for PHP, so
writing a manual is an unaided and thankless—yet required—job. However, this
shouldn’t do harm to your productivity.A complete manual should be designed very
much like a small book, featuring the following items:
n Introduction
n Table of contents
n User’s guide
n Technical documentation
n Developer’s guide
n Complete function reference
The user’s guide should describe in detail all features of your application’s interface (if
it has one) for a standard user. Don’t get too technical in this section, as it should only
be a “how to” kind of description. Be sure to cover every aspect elaborately.The
technical documentation should be written for technically interested users and
administrators and should contain technical requirements of your application, used and
introduced standards, as well as information about internal data processing if it would
be of any interest to the reader—and of course as your licenses permit. If you’re allowing
customers to see and/or modify the source code, include a developer’s guide to
explain the project’s structure, data flow, and internal relationships, as well as a function
reference listing all functions (including internal functions) along with a complete
description.
If you’re working on a team, professional technical writers are a great addition to
the crew—they have experience in creating in-depth technical documentation, as well
as enough time for writing it. Having a team member who’s occupied with development
also write the documentation creates a lot of additional stress, since developers
are usually busy enough trying to keep the deadlines.
|
|
|
|
|
|
| Link Partners: Asia florist, Flowers to India, Hong kong flowers, Site submit, Cheap web hosting, China florist, Japan florist |
|
