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?"

Comments

PHP.net

[unixbob]

If you look at the docs for PHP, the online version has lots of comments underneath posted by users which either explains the docs in a different way, or adds their own experiences of doing similar things in a different way, or just better ways of doing what the docs suggest.

Re:PHP.NET

[You're All Wrong]

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.

Re:PHP.NET

[BrynM]

I think we may both be right, but may be looking for different things. I tend to learn more about coding from looking at examples - even wrong ones. To each his/her own. I'm off to go look at Eric Weisstein's MathWorld now. Thanks for the reference to it. It sounds interesting.

PHP.NET

[BrynM]

The best example of user annotated documentation I have ever seen. In fact, the user comments are more valuable than the (rather sparse on each item) regular documentation.

Go explore it a while. Especially look at the functions individually. I even think it's overall the best documentation site I've seen yet.

Most of them don't even RTFM

[cloudless.net]

... and you expect them to WTFM?

TikiWiki CMS/Groupware

[dheltzel]

Tiki (or here if that gets slashdotted) does this by using the app to creat the docs for the app. It's sort of recursive, but it works. Users can either modify the docs themselves, or add a comment to the page and let someone with more time/expertise update the actual page. The really shy folks can also send a private message to the page creator if they like.

Disclaimer: Yes, I'm one of the developers and am trolling for new users. You can't blame a guy for trying, right?

Stay Away From Wiki

[marvinx]

I would recommend against using a Wiki clone. While it is great for the writer, it totally sucks for a reader.

A Wiki is just like a giant bathroom wall. Tons of information, and completely no organization or flow. There is no editor marking which is good and which is bad.

If you do go to a Wiki, you'll need someone there to continually categorize everything and organize it. Without a content manager, the Wiki becomes useless very quickly. Even though there might be tons of good information in there, no one will know how to find it.

Re:Stay Away From Wiki

[WuphonsReach]

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

Barriers are a Good Thing

[JohnQPublic]

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.