This section of the chapter does not deal with the specifics of
organizing documentation in the peardoc standard,
but instead with how to organize documentation logically.
First, every package solves a problem.
What is this problem?
Try to figure out what assumptions your end-users might not have
about the problem (they may not realize that this is a problem
that needs solving).
For instance, a template package solves the problem of both separating
design from code, and separating business logic from display logic.
If possible, explain the problem in terms that even a novice
programmer can understand.
Next, how does the package uniquely solve the problem? This is
something that most documentation lacks.
For example, there are many template engines.
All of them solve the same problem, but
none of them do it in the same way.
A block-based template engine does not have any logic at all,
whereas a template like Smarty defines a whole new template language.
Some template engines compile their templates, others don't.
What is unique about your package?
Can someone who has never seen the code get a good idea
of how it solves the problem?
Provide examples! Start right away with simple examples that
shows the basic feature set -- they will show users how to
quickly start using the package.
More complex examples will help the users in understanding advanced
ways of using the package.
If your package exposes complex interfaces or multiple constants
that can't be fully explained in one or two examples (which is
very likely), do not miss to explain them thoroughly in the
documentation.
Document any interfaces that users must use, such
as a database DSN, command-line arguments for applications,
configuration file contents, or any other non-code element.
Last, proofread your documentation.
If possible, have someone else who is not as familiar with your project
take a look at the documentation.
They will catch assumptions that you have missed.
Mexico | Web Advertising | Power Rangers | Myspace Unblocker | Song Lyrics