Subject: RE: mechanised documentation and my business model solution
From: "Anderson, Kelly" <KAnderson@dentrix.com>
Date: Fri, 24 Mar 2006 19:56:31 -0700

 Fri, 24 Mar 2006 19:56:31 -0700
> 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. :-)

I would pay for it if it existed, but the liklihood of it existing seems
fairly close to 0 based on current offerings.
 
> 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.

If you don't like the way a Wiki is organized, then reorganize it. I
also agree that Wikis aren't the silver bullet, but they are very
useful, and I wish SourceForge would put a Wiki page up for every
project they host. That would be very cool, wouldn't it?

> 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.

I agree that Wiki software COULD be improved for purposes of
documentation. It's a project I'd like to tackle someday.
 
> > 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.

Absolutely agreed!

-Kelly





E-Mail messages may contain viruses, worms, or other malicious code. By reading the
message and opening any attachments, the recipient accepts full responsibility for taking
protective action against such code. Sender is not liable for any loss or damage arising
from this message.

The information in this e-mail is confidential and may be legally privileged. It is
intended solely for the addressee(s). Access to this e-mail by anyone else is unauthorized.