Revdocs on a wiki

Timothy Miller gandalf at doctorTimothyMiller.com
Thu Oct 27 23:29:02 EDT 2005


Hi Dan,

Sorry you think it was a rant. I guess it might have been. It's 
embarrassing to rant, when that wasn't your intention. <:-|

>--snip--



>I wonder why it is that everyone thinks s/he can write better 
>documentation than the professionals


Good comment, but it's not quite what I intended to say.

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.

A very large number of users (if there are lots of sophisticated 
users, and few pimply faced vandals) can edit each other, in large 
degree. That's the beauty of the wiki model. As I understand it, 
wikiPedia is working out pretty well, with very little editorial 
oversight. The number of intelligent users with good intentions 
overwhelms the much smaller number of vandals and misguided users. 
(Some degree of editorial oversight is probably needed on many wikis, 
nonetheless.)

Sure, some users would bloat entries. But then, other users would 
prune them. When I look at the wikipedia, the entries I see are 
remarkably concise. E.g., I looked up iChat today. It was a very good 
entry, with all the links a guy could wish for. It eliminated the 
need for several dumb questions on some peer support group.

In other words, the users *aren't* as knowledgeable or skilled as the 
engineers, but their lack of knowledge is overbalanced by the size of 
the user community.

Beyond that, engineers don't always write well, and writing 
documentation clearly is a very difficult task. No matter how 
carefully documentation is edited, users will always find passages 
that should be clearer, or more extensive. Optionally extensive -- 
via hyperlinks. E.g., "Click here for a more detailed explanation of 
this topic."

>I know most people don't realize how much software QA and debugging 
>is done by the doc staff at major tech companies, but I can assure 
>you it's a huge contributor.


That makes sense. A docWiki starting from scratch for Rev has always 
seemed like a dubious proposition, to me. Better to start with good 
material. Doesn't necessarily need to be Rev's copyrighted 
documentation, though.

Rev might figure out a way to allow a wiki community to supplement 
and clarify the copyrighted docs, in a format convenient for all 
users, without giving up the copyright.

>In trying to describe how something works or when to use some 
>feature, the writer has to stand in for the uneducated user and try 
>things that the engineers never thought a user would do.


Novice users can speak for themselves, in many cases. If a novice 
user misunderstands, makes mistakes the engineers never anticipated, 
solves the problem, eventually understands better -- then the user 
can go back to the docs, figure out which part was misleading or 
incomplete, and improve it a bit. Repeat times many. Seems like this 
process would eventually out-perform the best possible team of 
engineer/writers.

>So while it is absolutely true that users can add a great deal to 
>the information base from which a tech writer works and while it's 
>certainly often true that end users could suggest things the tech 
>writer didn't think about, the idea that users should be allowed to 
>*edit* (as opposed to comment on) documentation makes as little 
>sense to me as the idea of allowing the engineers at customers' 
>companies to edit the source code of the product.


I've never meant to suggest that novice users should have unlimited 
editing privileges. I agree with the above paragraph, more or less. 
(It's possible that more experienced users would edit bad edits -- 
but that doesn't seem certain.) It probably makes more sense for 
novices to comment only, as you say. More sophisticated volunteer 
users would probably be able to take the comments submitted by 
novices and turn them into good edits and additions.

One possible model -- Participants could earn higher levels of 
access. Sort of like MVPs on microsoft's peer support groups. I don't 
claim this is the best possible model. Could be too complicated.

></rant>
>
>Several years ago, I headed up a project which involved an extensive 
>documentation effort and this same issue was raised. I like the way 
>we solved it. Furthermore, I happen to have access to the tool and a 
>server where it could be deployed and would make both freely 
>available if: (a) at least one or two others would be willing to 
>share site management and editing chores; and (b) the community 
>thinks it's a good idea. The approach we used was akin to a 
>discussion board. Each section of the docs was a topic on the board. 
>Everyone who was a member (and that term could be loosely defined, 
>of course) could add their comments to a section of the docs. There 
>was also a general topic area where people could post questions and 
>suggestions about the docs in their totality. Periodically, an 
>editor assigned to a given section would go through the comments, 
>incorporate the suggestions that made sense, edit the topic, create 
>a new topic on that section, hibernate the old, and move comments 
>that remained relevant to the new topic area.


You know this industry way better than I do. This might be a superior 
model. OTOH, this model could keep more than one editor/engineer 
pretty busy -- I'd estimate. If Rev doesn't have the resources to 
support this kind of model, then we're back to (mostly) volunteer 
authors and editors on a wiki.

>
>At the same time there was a way for any interested party to: (a) 
>see the docs without the comments; (b) navigate using only the 
>"official" docs; and (c) view and print (and save as PDF) all or 
>some of the currently official documentation. This model is called 
>"managed open collaboration" and I think it presents the best of all 
>possible worlds in terms of encouraging and incorporating useful 
>input without disrupting the accuracy or utility of the original and 
>modified documentation.


That makes a lot of sense. And it's very generous of you to offer your efforts.

I don't mean to cheerlead for a specific model. I don't have the 
expertise to compare models wisely. I want to share a vision, and 
vote in favor of it now and then:

--A product we admire, and depend on.
--A complex product, which needs the best possible documentation to thrive.
--A community of loyal and reasonably knowledgeable users, many 
willing to volunteer writing/editing/exampling/hyperlinking time.
--Continuous quality improvement for the docs.
--The inherent advantages of various wiki-like models.
--The likelihood that a well-run wiki can further grow and bond a 
community of users.
--A possible good fit between various wiki-like models and rev itself.

Why have I gotten all preoccupied with this? I don't really know. 
Maybe I should shut up and leave this matter for the experts. I just 
sort of got a bug up my data bus.

Upon further reflection, I've daydreamed about this sort of thing 
ever since I first heard about hyperlinks and the www. It strikes a 
romantic, idealist chord in me. Human beings are great at 
collaborating to make war, or to destroy the planet foolishly. Maybe 
new technology can make it possible for human beings to do *good* 
things more often. Anything written or decided by a committee usually 
turns out badly. But wikis seem to maximize the advantages of 
collaborative efforts, while minimizing the stupidity of committees.

I've always wondered if a well-run wiki could produce a great novel 
or textbook, for example, or solve a difficult mathematical problem. 
As far as I know, these possibilities remain untested.

I'd way rather shut up than appear tiresome and foolish to all. I 
would have lost interest in this topic many threads ago, but it keeps 
coming up. I get the impression that some other subscribers share 
this vision, approximately. If not,  I'm done.


Cheers,



Tim




More information about the use-livecode mailing list