Writing documentation
Instead of a long and boring description for writing documentation using DocBook, we would like to point you to a bunch of "reference documents", from which you should be able to learn quickly:
-
Console_ProgressBar - small documentation for a small package
-
System_Daemon - medium sized documentation on several pages
The scope of your package's documentation should be:
-
Explain which problem your package solves
-
Describe differences to other packages solving identical or similar problems
-
Give example how to use the package
-
(Maybe) give an introduction to concepts your package uses and that the user probably does not know/is not aware of
The documentation should not repeat the API docs! You should only link to it. The documentation for older packages often contains the whole API reference, but that is not the manual's scope anymore - phpDocumentor does a much better job at generating it automatically.
Package documentation file structure
| Filename | Description |
|---|---|
packages/ |
Directory containing all package-specific documentation |
category.xml |
Description of a category |
category-entities.xml |
File with links to all packages in that category. Exists in english documentation only. |
category/ |
Directory with documentation of packages in that category |
package.xml |
Main file for documentation of a specific package |
package/ |
Files for the package documentation are collected in
here, e.g. examples.xml |
Committing changes into SVN
Before committing your changes into peardoc SVN, test and build it! This is absolutely necessary - it makes sure that other people writing documentation can build the manual without problems, and that the official pear.php.net build works.
The manual on pear.php.net is build once a week, 12:00 UTC every sunday. If it breaks, it will take a whole week until the next build attempt is made!
So do not commit updates shortly before the main build happens.
If you don't have peardoc karma, write to the peardoc mailing list to get it. It is also possible to send a patch to the list and get someone with karma to commit it.
Tips for good documentation
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.
-
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 show 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), it is still important 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 elements.
-
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.
Software assistance
PEAR documentation is mostly written using plain text editors like
vim or Kate. XML editors mostly
don't help enough to be more useful than text editors; plus no tool yet
is able to work with the entity linking structure used in
peardoc.
One way to get documentation easily is writing initial package documentation using an XML editor like XXE, and make the necessary adjustments for peardoc after that. After doing that, you probably won't be able to use the XML editor anymore without losing data.