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
_______________________________________________
use-revolution mailing list
[email protected]
Please visit this url to subscribe, unsubscribe and manage your subscription
preferences:
http://lists.runrev.com/mailman/listinfo/use-revolution
