Slashdot Mirror
Writing Open Source Documentation?
An anonymous reader asks: "I'm an Open Source guy that runs Linux, and suggests Firefox and OpenOffice to friends. Now, I'd like to give back, but the problem is that I'm not a coder. So, how do I go about writing documentation, and what kind of projects should I look into? What are some stellar examples?"
In fact this is why I think FOSS can get a bad reputation with many PHB's. The quality of the documentation varies, it's either nonexistant or pretty complete. The best set of docs I've seen for free software would either be the Subversion book, the Gentoo install handbook or the manuals that SciLab has. Really goes through everything in-depth. Also a good man page and a '--help' option for CLI utilities is always welcome. However a lot of people and 'new converts' to free operating systems tend to stick with the GUI for help, so HTML documentation that's easily accessible is a must. In fact it's usually buried somewhere in /usr/share or the like, and often programs don't tell you how to get at it easily.
Read existing documentation - some other posters already mentioned a few nice examples.
Get in contact with the project of your choice and ask them what they need. Walkthroughs, Tutorials, Manuals, technical documentation.
Read some more - style guides for technical writing. That is quite different to the writing of essays in school. (To get you started, try this one I wrote as a jump off point. Some technical journals also have guidelines for writing, read those too.
Disclaimer: I'm not claiming that my paper is the best guide out there, but it is decent for getting started into technical writing.
I would say find a project which is actively friendly to new contributors. This is something our project (http://www.bongo-project.org/ - mail and calendaring, etc.) tries to be really good at, although obviously you can always improve.
The reason I say that is that to contribute, you inevitably need help at first, and you want to see your work be included in the project. If you pick a project where it's difficult to get involved, or where you contribute patches which end up rotting in the bug tracker, you'll get frustrated and feel your work is for nothing. On the other hand, if you create things and the project accepts them with open arms, you'll feel that you've really achieved something.
"Elmo knows where you live!" - The Simpsons
I am TheRaven on Soylent News
A cornerstone of documentation in the Unix/Linux/*BSD world is the man page, a very concise and targetted form of documentation that programmers and sysadmins in particular find extremely convenient, especially for documenting library functions and commandline tools.
Unfortunately many FOSS projects don't provide man pages, not even a single one to document the commandline options of an application for example.
This is where newcomers to FOSS technical documentation could make a wonderful contribution. Just take any existing READMEs etc, or run an app with -h or --help or whatever it takes to find out how it's used (perhaps read the sourcefile headers, even if you're not a coder), and make a corresponding man page. That would be totally wonderful, and much appreciated by many.
What's more, there are many tools available to help you along the way. One good place to start is with perldoc/perlpod and the POD format (which are not tied to Perl at all even though they came from that community). These very handily allow you to generate both man pages and HTML equivalents extremely easily, as well as LaTeX format for high quality output and publishing.
As should be apparent, the best documentation system allow you to generate multiple different forms of output from a single input, and man pages + HTML should be the very least that is acceptable to you. (HTML-only documentation is pretty useless in many situations.) Be sure to check out the man2html suite too, which is very handy.
The Doxygen suite is very powerful as well, but automatically extracted man pages are no substitute for the real thing written by a competent technical author. That's where you come in.
It's great to hear of new people wishing to help with FOSS documentation, and man pages are a key element of the overall picture and an easy place to start as well. They really are the bedrock upon which much of FOSS is based, and deserve attention.
"The question of whether machines can think is no more interesting than [] whether submarines can swim" - Dijkstra
Err...actually...you can RTFM on how to write documentation. I should know - I wrote one:
LDP Author Guide
So you fool around with it, examine every menu entry and every option, and document their effects one at a time. Then you have a reference for yourself, but it's in reverse: command to task rather than task to command. Just flip it around and you're done. (The flipping might take significantly longer than the initial exploration, though.)
Then approach the developer with the documentation in hand. Better yet, find out what GUI toolkit the project uses, what sort of help system is offered, and what file format that system uses. Then format your documentation according to that system and offer the developer the formatted version.
It helps, though, if you offer to maintain the documentation. That way, bugs in the docs don't affect the developer.
I beg to differ, as a user of MS development and office products I can tell you that their documentation sucks. I would say that it is as useful as having no documentation at all most of the time. For good documentation check QT, postgre or gcc, all of them open source projects.