Revdocs on a wiki

[Timothy Miller]

I have mixed feelings about what I'm about to say. I expect that the 
new docs will be a big improvement. They might be excellent. Rev 
deserves a lot of credit for efforts to enhance the docs. I don't 
want to see that deprecated. I suspect Rev cares about their users 
more than most technology companies I could name.

OTOH, in my opinion, it's time for the concept of "continuous quality 
improvement" came to the world of technical documentation. And, being 
a Rev loyalist, I'd love to see Rev do it first, maybe with a Rev 
interface, if feasible.

(It would be totally cool if a commercial product, intended for this 
purpose, could be built mostly with Rev. It would have to be 
extensible and flexible. But this seems feasible -- not that I know 
diddly squat about that sort of thing.)

With a wiki, continuous quality improvement could mean, "it gets a 
little better every five seconds." (For that matter, the Wikipedia, 
today, might get a little better every five *milliseconds*!)

Some published docs are better than others, but none get anywhere 
near optimal. Technical documentation is inevitably obsolete the day 
it is published. There's always room for updated information, clearer 
explanations, different contexts, more examples, more "see also" 
links, better search capacity, and so on. All those little 
improvements really add up over time. In addition, hyperlink 
technology (ahh... my old friend, HyperCard) can greatly enhance 
convenience and real-world useability. Multiple forms of indexing, 
for instance. Terse, less terse and verbose versions of the same 
topic, for another. (The beginner will likely want the verbose 
version. The experienced user will not want or need to wade through 
it.) I've never seen hyperlink technology live up to its potential, 
even though it's been in use for fifteen years or more. A docWiki 
like the one proposed could be the first time. (Wikipedia is already 
pretty good, I guess. I don't use it that much.)

I have some doubt about whether it would ever be profitable for a 
private company to write docs like those that could arise 
spontaneously from a wiki. Printed on paper, they might fill 10,000 
pages, and would still lack the convenience of hyperlinks, search 
capacity, and so on.

When docs arise spontaneously from a wiki, they will be much cheaper 
to produce -- almost free, after the early drafts, except for keeping 
out vandalism and ignorance. And users might also police the 
vandalism and ignorance at no cost (possibly). For the manufacturer, 
how good could it get?! Even if a company tried to write optimal docs 
and practice continuous quality improvement in the docs, users, given 
the opportunity, could always improve whatever the engineering and 
technical writing staff came up with, with no publication delay.

Just my .000002 cents worth. Have a nice day.


Tim


>Dear list members,
>
>Regarding the recent debate about extracting the current revdocs and 
>putting them on a public wiki. We have discussed this here, and we 
>feel that at this moment in time such effort would be largely 
>wasted, as the docs are under active review right now. However at a 
>later date we plan to make space available on our server for a 
>documentation wiki, if people are still keen to work on that.
>
>If and when a wiki is set up, it will be necessary to have a 
>copyright notice incorporated, as the documentation is copyright 
>Runtime Revolution.
>
>Warm Regards,
>
>Heather
>
>Heather Nagey, Customer Support Manager
>Runtime Revolution Ltd
>www.runrev.com