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?

[Anonymous Coward]

How about PHP's documentation?

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

[BrynM]

There seems to be a general consensus here ;)

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.

Re:PHP.NET

[WuphonsReach]

The big problem with places like PHP.NET, MySQL docs (with the user comments) is that there is no way for the comminity to indicate which posts are good/bad.

A good system might be the scoring system that Allakhazam uses. Initially, your comments on things are rated at a score of 2.00, and anyone who has an account can mod your comment up/down (1.00 is the lowest score, 5.00 is the highest, default filter is to hide comments under 1.50). As you get more and more posts rated at higher levels, your initial posting score gets higher.

Re:PHP.NET

[You're All Wrong]

Very good point. I was thinking about that, but I'd had a few beers and I completely forgot to type it in! I didn't know that any such pages used a moderation-style system. I can't say I know Allakhazam, I'll have a quick google, and see if it's well implemented.

The thing is sometimes that the clumsy hacks are sometimes _useful_ to know. I wasn't being fair above. When there's a bug in PHP that needs to be coded around, proper respect to the guy that first posts the workaround. However, within weeks or months that code-around is irrelevant as PHP2.0 or whatever fades into non-existance. If anything it's an embarassment to PHP to have such kludges still visible.

YAW.

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.

Re:Welcome to GNU GVideo GProfessor!

[BrynM]

Lame. That would actually be funny if it weren't posted everywhere. Time to come up with something new, unless of course you didn't write this in the first place. Then it's time to steal something new. Good luck!

Most of them don't even RTFM

[cloudless.net]

... and you expect them to WTFM?

Lots of places do this...

[stienman]

Check out, as an example, PHP's documentation

-Adam

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?

Re:Welcome to GNU GVideo GProfessor!

[geekoid]

"Time to come up with something new, ..."
kudos for not using trhe obvious pun. Unless you didn't see it. In that case, your going to be hunted done by the Punsiter.

That was bad, I should come up with something GNU...

bork bork

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

The Zope Book is user commentable

[BitDancer]

The main documentation for Zope was made user annotatable using a
product called "TalkBack" developed by one of the Zope developers.
It worked moderately well, I think. Fewer problems than the PHP
community had, I think, probably because the Zope community is
smaller and so you get fewer of the clumsy-hack notes. I think if
you take the tack of *authorizing* people to comment, then you can
avoid that problem to a considerable extent. Also, if you can
maintain the schedule of incorporating updates within two or three
weeks I bet you could mitigate the rouge comment problem almost
completely.

gallery

[an_mo]

Check out this php-based gallery software. They used to have an entirely wiki-based doc site, but it looks like they switched to something else.

IN general, wikis are good, but you need somebody in charge of checking revision constantly and maintaining style consistency across pages. Users tend to make a mess of the wiki site.

Mysql.com

[Anonymous Coward]

Mysql has a wonderful /docs directory with user comments. I don't think the tech is important; what's important is the moderation. The really valuable contributions should be caveats, unanswered questions, code snippets and such, or clarifications to the docs. If you are really at the 'thousands of pages' stage, then I guarantee that there are ambiguities, ignored scenarios, and unintended interactions that the users, and only the users, can point out.

But moderation is the key. You need a hand at the controls that has a) a VERY good understanding of the software and b) a merciless right pinky.

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.