Paul Jones has written an interesting piece about documentation in the PEAR project, in which he argues very convincingly for using wikis for end user documentation.
I actually think that last point bears repeating: using wikis for end
user documentation. I talked to Paul about this issue at
php|Tropics, and both of us use phpDocumentor quite religiously. However,
API documentation is very different from end user documentation. And the
issue with documentation at the PEAR project has to do with the fact that
there are many projects with little or no end user documentation -- which
often makes it difficult for a developer to determine how a module might be
used.
The often-cited barrier for this is that end user documentation on the PEAR
website must be done in DocBook format.
For the record, I hate maintaining DocBook format. I
created the tutorials for Cgiapp using it, and I dread having to go back
into them to update or add new sections.
Why? Well, for starters:
- I don't use XML on a daily basis. If I need to deal with XML, I
typically create a template and have a script fill it. Or I use a parser.
But I don't write it by hand.
- DocBook doesn't use the same tagset as HTML. This means that I have to
try and remember different tags, and which work in which arena.
- Related to (2) is that because the actual tags available can vary based
on the DTD, VIM doesn't have keystroke macros to create the begin/close
tags. This is a feature I use in editing HTML daily, and which speeds up my
writing time. So, writing DocBook is slower than writing HTML (or plain
text) by a significant factor. (Yes, I could write VIM macros for often
used tags, but then I'd need to learn more about VIM scripting, and who has
the time?)
- I already know and use HTML on a daily basis. I use plain text on a
daily basis (did I mention I use VIM?). I'm comfortable in these
environments. Why would I use anything else?
But I think the point that is often overlooked is that PHP was written
to create web pages. Let that sink in for a moment. Why would a PHP
project encourage writing documentation in anything other than the language
of the web, HTML? Indeed, why would it discourage writing web-ready
documentation?
As Paul noted, while wikis may not be great for all documentation purposes,
they're more than adequate for most. In most projects, you're not
going to need tables to document the project; several levels of headings,
paragraphs, and some list elements will do the trick. Wikis can do all of
these things. And they allow these things to be done easily, and for the
results to be instantly available (rather than on a once-daily basis, as is
the case for the PEAR web documentation, which must be compiled from
DocBook).
My suggestion? Since DocBook can be exported to almost anything, export the
PEAR documentation to a wiki format, and then use wikis for all but the most
complex documentation. Do the complex docs in HTML, or, if you
really feel the need for an output-agnostic format, use DocBook
then. (My guess is that if the above were implemented, we wouldn't see much
DocBook after more than a year.)
Maybe by reducing the barrier to creating usable end-user documentation,
we'll start seeing a proliferation of documentation on PEAR to augment the
great code that's been appearing there.
