Revdocs on a wiki
chipp at chipp.com
Thu Oct 27 22:48:21 CDT 2005
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.
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.
More information about the use-livecode