Slashdot Mirror

← Back to Stories (view on slashdot.org)

Large User-Maintained Documentation?

Posted by Cliff on from the a-smart-idea dept.

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

4 of 22 comments (clear)

  1. PHP? by Anonymous Coward · · Score: 1, Informative

    How about PHP's documentation?

  2. PHP.net by unixbob · · Score: 3, Informative

    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.

    --
    The Romans didn't find algebra very challenging, because X was always 10
  3. PHP.NET by BrynM · · Score: 2, Informative
    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.

    --
    US Democracy:The best person for the job (among These pre-selected choices...)
  4. Mysql.com by Anonymous Coward · · Score: 1, Informative

    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.