Subject: RE: mechanised documentation and my business model solution
From: Rich Morin <rdm@cfcl.com>
Date: Fri, 24 Mar 2006 18:48:10 -0800

At 7:24 PM -0700 3/24/06, Anderson, Kelly wrote:
> I believe that open source code deserves open source documentation.

Deserves is a strong statement.  I would agree, however, that open
documentation is a Good Thing for Open source projects.  (OTOH, I am
quite willing to pay for proprietary documentation, if it exists and
I need it more than I need the money. :-)

> As such, the best way to document any open source project in my
> mind is with some kind of Wiki.  Then, if a user finds a problem
> with the documentation, it can easily be fixed.

I'm a fan of wikis, but I don't believe they are a panacea.  In
particular, I think that there is a chaotic aspect to many wikis
that gets in the way of their utility as documentation.  Full-text
search is a wonderful capability, but if I'm trying to research a
topic, it's nice to have an organized way to look for the answer.

I'm also a strong believer in making documentation easy to annotate
and update.  A user should be able to ask questions or make comments,
knowing that interested parties will hear about it and that the
results of the interchange will be kept for future use.  Wikis can
(but may not) provide for this.

> As for comprehensive and detailed documentation, succinct and
> accurate is usually better.

My take is that several forms of documentation are needed.  Tutorials
and overview documents are needed and must be written by humans.  If
I just want to know which functions use a data structure, however, I
don't want a human to waste time compiling the information.  Hence, I
would argue for a mixture, with appropriate navigation, search, etc.

-r
-- 
http://www.cfcl.com/rdm            Rich Morin
http://www.cfcl.com/rdm/resume     rdm@cfcl.com
http://www.cfcl.com/rdm/weblog     +1 650-873-7841

Technical editing and writing, programming, and web development