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
Have a look at any of the 100s of games and other applications written for the Linux desktop.
Go to the Help menu.
Notice the only thing there is "About".. which is really helpful when it comes to figuring out how you play this puzzle game.
What that About box does tell you, however, is the name of the author. Contact that person, offer to write a help page, they'll tell you how.
How we know is more important than what we know.
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 ";_
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
The manual that comes with GnuCash accounting program is not just a user guide, but a simple and easy-to-understand accounting primer suitable for the newbie who isn't sure why s/he would need to know about accounting in the first place. Depending on what you wanted to contribute --whether you want to be a prolific updater of man pages for semi-geeks, or focus on fine user guides for one project-- this may or may not be the type of example you want, but it's something that made the GnuCash program much more valuable for me.
I think one valuable attribute to have as a documentation writer is to be able to see it from the point of view of the newbie. Know what questions they would have, and give examples. (One thing that bothers me about man pages is that many of them don't give examples.)
404555974007725459910684486621289147856453481154 in hex is "You sank my Battleship?"
[GPG key in journal]
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.
It is great to give back to the community. I can help hook you up with the right folks if you want to a "how to" or develop a checklist or cheat sheet for an open source tool. We post them for the community to use as they will on http://www.sans.org/score, just drop me a note.