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?"
Oh wait....
Do not try to read the dupe, thats impossible. Instead, only try to realize the truth
What truth?
There is no dupe
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.
It is great that you want to contribute with documentation. A great program/framework/OS/whatever that no one can use because there is no documentation to be found is worthless.
Sun has published a pretty good book called Read Me First! - A style guide for the computer industry. Covers "writing styles", legal guidelines, writing for an international audience, types of techical documents, and so on. Recommended. For a fun example of how NOT to write, read this page and see if you can figure out which sentences refer to the "old" bad way to do animations, and which sentences refer the new recommended way (the rest of the tutorial is pretty good though, and I really appreciate the time and effort people have spent on it - I just wish someone who knows more than me about Blender could rewrite that particular section.)
Which project to contribute to - well, you had three good examples there. Just pick any project you are passionate about and comfortable using, try to think about what documentation you would have found handy when you was learning to use it. Start writing that.
Being bitter is drinking poison and hoping someone else will die
Just remember:
Documentation is like sex, when its good, its very very good, and when its bad its better than nothing.
$_="Slashdotter";$syn="OTT";s;..;;;sub _{print shift||$_};s!ash!Perl !;s=$syn=ack=i;tr+LLEd+BLAH+;_"Just Another ";_
Do not try to read the dupe, thats impossible. Instead, only try to realize the truth
What truth?
There is no dupe
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