Revdocs on a wiki

[Chipp Walters]

Timothy Miller wrote:


> The engineering team must certainly begin the documentation process. If 
> it's a simple application, then maybe the docs written by the engineers 
> are as good as they can be.
> 
> But if it's a very complex application, or development tool, or 
> whatever, then the documentation is *never* optimal.
> 
> If the engineering department had unlimited resources, and the desire to 
> engage in continuous quality improvement, then they would likely write 
> better documentation than users on a wiki.
> 
> But no engineering department has unlimited resources. Beyond that, 
> continuous quality improvement on documentation is an infinite task that 
> would not appeal to many engineers. Writing more than one version of the 
> same entry, adjusting to the sophistication of the user -- I don't think 
> many engineers would like that.

Tim,

You might want to reread what Dan was 'ranting' about. He's talking 
about professional writers, not engineers. Jeanne DeVoto (the original 
revDocs writers) and Dan Shafer are both professional writers, each with 
multiple technical books and manuals published. Back in the HyperCard 
days, they were both well-published and well-read authors. I'm not sure 
I know *any* engineers who can write as well.

Though, after seeing Sivakatirswami's post regarding PMwiki and PDF's, I 
might be more inclined to consider a Rev backed wiki experiment. The few 
wiki's I've been involved with in the past were:

1) Way too slow
2) Not well organized
3) Way too slow
4) Never really got to a finished state where they were really helpful

Did I mention how slow they were? :-)

But, with the dedicated users here on this list, and some basic 
housekeeping rules (that means limited TAOO references Xavier! ;-), it 
might be interesting to see what happens. Perhaps with the shared 
enthusiasm, Kevin et al might greenlight a test wiki.

Even if RR did, I suspect there would be a lot of time doing front end 
analysis of how to organize the content so that it can be reused. One of 
the good things about the docs in the current XML state (not the doc 
viewer, but the underlying data structure) is that it can be repurposed 
quickly. This is great because many different users including Jerry 
Daniels, Richard Gaskin, Wouter, Geoff Canyon and  myself have been able 
to use the XML to create different ways at looking at the documentation.

Some of these are free, others cost. But the beauty in XML is that it 
doesn't 'lock' the content inside a display presentation format. I 
assume wiki's can do the same thing.

best,

Chipp