Slashdot Mirror
Large User-Maintained Documentation?
SysKoll asks: "I am working for a company that has release several open source contributions. Our flagship product, often updated, has thousands of pages of documentation that are constantly revised to stay relevant. Right now, users who find a doc defect send an email, and the doc is updated both on the web site and in the updates, but it can take weeks. I am trying to convince my upper management that the way
to go is to turn the doc web site into a wiki-style community site, where registered users can annotate pages directly between official revisions. Does anyone know a large set of web-published documentation that is annotated using this kind of user feedback?"
I have to take a contrary stance.
The offical documentation at PHP.net is great. Slightly sparse in places but on the whole pretty usable.
I learnt PHP from those pages, and those pages alone.
_However_ the user-contributed feedback was _abyssmal_. It was contributed by people who knew just enough to get things done in one clumsy way, and that's why after hours of trying they thought it would be useful to share their experience and their results.
The problem is, it's usually a clumsy way, and only useful to others who only a very limited ammount.
While that's probably better than nothing for some of the auxiliary library routines, where very few people have expertise, it's downright dangerous for the core language areas.
However, I'm a bit of a language lawyer - I want specifics, I want dry boring facts, I want grammer productions - and my tastes probably aren't the same as everyone else.
To me wiki's are a turn off.
For things that are have user-contributed parts, I prefer things like Eric Weisstein's MathWorld, which has strict editorial control within Wolfram. Just today I submitted an error report, and within a few hours Eric had replied to say that the update would be out soon. OK, it's 8 hours later, and it's still not updated, but I bet that it only takes a day or two. That's swift enough for most people.
In particular when you consider many of the comments on
PHP.net are several years old. What difference does a day or two make now?
To the story poster - just get them to streamline their process.
If it takes more than a day or two, you're doing it wrong.
YAW.
Your head of state is a corrupt weasel, I hope you're happy.
Wikis are designed to lower the barrier to editing the content as low as possible. That is, the more hoops you make people jump through to tell you about a problem, the less people will bother. And not all wiki clones are identical, some include revisioning systems, different levels of access, peer review, etc.
Regardless, no matter what system you go with, you have to have a gatekeeper / editing team to periodically seperate the wheat from the chaff, to consolidate 3 pages of notes down into a easly digested single page.
The big advantage of a wiki is that if you find something wrong you can easily/quickly fix it (or submit a revision if it's a managed wiki). Which is a reasonable attempt at turning the entire documentation base into an open-source project. (Not all open-source projects accept changes willy-nilly from the end-users.)
Wolde you bothe eate your cake, and have your cake?
If I want partially-inaccurate information, off-topic rants, and "it worked for me this one time in band camp" anecdotes, I'll search Google or read netnews. Software documentation has to be just as good as the software itself - something we often don't get in Open Source becuase of the "code first and foremost" perspective.
It should be hard to mess up documentation, just as hard as it is to mess up code.