NYCPHP Meetup

[Kenneth Downs]

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.

> Hey all --
>
> I just had a colleague ask about alternatives to phpDocumenter, which
> I've been using for some time now.  Does anyone have any
> recommendations?  What do people use in documenting their
> code/project?
>
>                                            -Chris
> _______________________________________________
> New York PHP Talk Mailing List
> AMP Technology
> Supporting Apache, MySQL and PHP
> http://lists.nyphp.org/mailman/listinfo/talk
> http://www.nyphp.org
>


-- 
Kenneth Downs
Secure Data Software
631-379-0010
ken at secdat.com
PO Box 708
East Setauket, NY 11733