Revdocs on a wiki

[David Bovill]

Well said!

On 28 Oct 2005, at 01:12, Timothy Miller wrote:

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