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?"
How about PHP's documentation?
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
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...)
"Don't fumble through boring man pages. Try my product!" - Richard M. Stallman, GNU Founder and CEO
GNU GVideo GProfessor is the leader in computer learning. We have taught over 5 million people, and we can teach you GNU/Linux, GNU/Emacs, GNU/gcc, and more! GNU GVideo GProfessor was founded in 1983 to provide consumers with training on software for their personal computers. Since that time, millions have successfully used and learned from GNU GVideo GProfessor's fool-proof "What-You-See-Is-What-You-Do" teaching method. The first lesson, GNU/Emacs 1.0, was available only on video tape. Over the years, GNU GVideo GProfessor has produced hundreds of titles on video, CD-ROM, and online. GNU GVideo GProfessor is the fastest, easiest way to learn computers. We guarantee it!
It's FAST! You'll be up and running in an hour! Don't waste time sifting through man pages, commuting to classes or seminars. Just pop in the CD-ROM and you're learning!
It's EASY! It's as simple as 1-2-3! GNU GVideo GProfessor's straightforward "What-You -See-Is-What-You-Do" approach makes learning as easy as watching TV!
It's CONVENIENT! We're ready to teach you day and night! With your busy schedule, you don't have time to waste at classes or seminars. Don't fumble through boring man pages. Whatever your schedule, we're ready when you are!
It's COMPLETE! These aren't short teaser lessons. Each 60-minute lesson takes you from installing the software to more advanced skills. And they're not just for beginners! We'll surprise you with the knowledge you'll gain!
Why Am I Making This Incredible Offer? I'm so confident that once you try my exceptional " What-You-See-Is-What-You-Do" learning method, you'll turn to us for all your computer learning needs.
* How it works!
The bonus gift and ANY TWO of the three computer learning CD-ROMs are yours free without further obligation, PERIOD. Take 10 days to decide if you want to keep the complete set of CDs. After your 10 day free trial, if you decide to keep the complete set, we'll conveniently bill your credit card just $69.95. Or simply contact our customer care number at rtfm@gnu.org if you decide to return any one of the lessons, and you will be charged nothing more!
Every day hundreds of people just like you learn with GNU GVideo GProfessor this same fast and easy way. If you decide to keep all three lessons, every five weeks you will continue learning by automatically receiving other GNU GVideo GProfessor subjects you have an interest in, billed on the same exact terms as your first shipment. Or simply call and cancel. Everything is up to you! But most important, you are never under any obligation to purchase a subject that you don't keep. Best of all, the bonus gift, and your choice of any two of the three computer learning CD-ROMs are yours to keep FREE!
gd
"Don't fumble through boring man pages. Try my product!" - Richard M. Stallman, GNU Founder and CEO
GNU GVideo GProfessor is the leader in computer learning. We have taught over 5 million people, and we can teach you GNU/Linux, GNU/Emacs, GNU/gcc, and more! GNU GVideo GProfessor was founded in 1983 to provide consumers with training on software for their personal computers. Since that time, millions have successfully used and learned from GNU GVideo GProfessor's fool-proof "What-You-See-Is-What-You-Do" teaching method. The first lesson, GNU/Emacs 1.0, was available only on video tape. Over the years, GNU GVideo GProfessor has produced hundreds of titles on video, CD-ROM, and online. GNU GVideo GProfessor is the fastest, easiest way to learn computers. We guarantee it!
It's FAST! You'll be up and running in an hour! Don't waste time sifting through man pages, commuting to classes or seminars. Just pop in the CD-ROM and you're learning!
It's EASY! It's as simple as 1-2-3! GNU GVideo GProfessor's straightforward "What-You -See-Is-What-You-Do" approach makes learning as easy as watching TV!
It's CONVENIENT! We're ready to teach you day and night! With your busy schedule, you don't have time to waste at classes or seminars. Don't fumble through boring man pages. Whatever your schedule, we're ready when you are!
It's COMPLETE! These aren't short teaser lessons. Each 60-minute lesson takes you from installing the software to more advanced skills. And they're not just for beginners! We'll surprise you with the knowledge you'll gain!
Why Am I Making This Incredible Offer? I'm so confident that once you try my exceptional " What-You-See-Is-What-You-Do" learning method, you'll turn to us for all your computer learning needs.
* How it works!
The bonus gift and ANY TWO of the three computer learning CD-ROMs are yours free without further obligation, PERIOD. Take 10 days to decide if you want to keep the complete set of CDs. After your 10 day free trial, if you decide to keep the complete set, we'll conveniently bill your credit card just $69.95. Or simply contact our customer care number at rtfm@gnu.org if you decide to return any one of the lessons, and you will be charged nothing more!
Every day hundreds of people just like you learn with GNU GVideo GProfessor this same fast and easy way. If you decide to keep all three lessons, every five weeks you will continue learning by automatically receiving other GNU GVideo GProfessor subjects you have an interest in, billed on the same exact terms as your first shipment. Or simply call and cancel. Everything is up to you! But most important, you are never under any obligation to purchase a subject that you don't keep. Best of all, the bonus gift, and your choice of any two of the three computer learning CD-ROMs are yours to keep FREE!
dv
... and you expect them to WTFM?
Check out, as an example, PHP's documentation
-Adam
Disclaimer: Yes, I'm one of the developers and am trolling for new users. You can't blame a guy for trying, right?
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.
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.
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 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.
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.