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