NYCPHP Meetup

[csnyder]

On 1/9/06, Kenneth Downs <ken at secdat.com> wrote:
> Here is a contrary opinion: Don't automate documentation.  I'm a big fan
> of automation and automate absolutely everything, always have, and have
> had great success doing so.  But no automatic documentation solution ever
> satisified me, and I've tried them all, commercial, open-source, and
> home-grown.
>
> I finally came to the conclusion that good documentation contains a lot of
> stuff that you just can't put into the source code, like example code,
> perhaps pictures, links, cross-references and so forth.  Because this
> information is different *in-kind* from the details you put into
> source-code-based documentation, it should be created in a different
> mental context as part of a different effort.  Once you are doing this,
> then maintaining auto-doc stuff in the source code means you are putting
> it into two places, which is bad, so you drop the docs in the source code
> because they are the less important.

But actually there is a need for both kinds of documentation.

The autodoc is the authoritative source for information about your
objects' interfaces, and maintaining *lightweight* documentation in
the code provides immediate benefits to core developers -- especially
if you use a smart IDE that can parse the autodoc and provide hints as
you write.

Once your API is mature, you can use a wiki or cms to build developer
documentation, which contains conceptual descriptions, code samples,
useful patterns, and diagrams -- illustrated with deep links to the
autodoc.

It's not about putting the same information in two places; it's about
having the details handled automatically in one place, so you can
concentrate on the big picture in another.

--
Chris Snyder
http://chxo.com/