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 ";_
Just look for the files with .c and .h extensions.
1) Find a project you're interested in
2) Find the mailing list for the project (for larger projects the documentation mailing list if it exists)
3) Introduce yourself
4) People there should help you get going
FWIW, the GNOME project is screaming out for more people to work on documentation (as I'm sure every project is)
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'm an Open Source guy that runs Linux
Wow! He should document himself.
As the author of an open source program, I get emails all the time from people saying they'd like code, like to write help/docs, or like to translate. I spend a fair bit of time explaining things to them, but often they never produce anything. I find this really frustrating, and it makes me less likely to want to spend time helping the next person to email me as they'll probably just disappear.
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
BUT the glass is starting to fill. The GIMP, OpenOffice.org and PostgreSQL are larger projects I particularly think have gotten it together with comprehensive user manuals and support sites. Others like FlightGear, which can be some versions behind, or MySQL, which I think is a little "chatty" for tech writing, get points for trying to be thorough.
Probably the biggest problem I see in open source documentation is what I call the "Worked? GOOD! Worked? GOOD!" syndrome. They only go through the steps of an installation or configuration as it works perfectly and seldom have a troubleshooting tree of hints for problem steps. Better hope you have a perfect vanilla installation/configuration or it is off to Google/usenet/blog hell.
The PHP Documentation Team is always looking for contributors. For an easy start, you could help by documenting undocumented functions, for example..
The Linux Documentation Project (http://www.tldp.org/) is the best place to start. You'll have to learn about the docbook format. You could always just start a more general open source documentation project.
My Hello World is 512 bytes. But it's also a valid Fat12 boot sector, Fat12 file reader, and Pmode routine.
Here's a personal observation. As of 7.04, I've switched to Ubuntu completely at home. When I made the switch, I assumed that there would be good software for usenet-centric tasks. Pan and Klibido are right there in the menu when you click on applications and look for something to add. Start 'em up and they look nice.
Then go look for the docs. Nothing. Zip. I never liked Agent so I didn't get a lot of experience with it under Windows, thus nothing in Pan looks obvious to me. Still, I'm stuck with Pan because it seems to be the only full-blown usenet reader for Linux that a Windows convert might recognize as what software should look and act like. That's why the docs are needed and they don't exist as far as I can tell.
I imagine it would be easy to find users who would derisively yell "Look at the stupid n00b!" in my direction. Some of them may try to make me look bad by pointing out some obvious source of docs that I've overlooked.
But here's my point: I'm not trying to make Pan look bad. It's no better or worse in this regard than lots of other programs. I cite it specifically because it's such a typical example. Linux for the normal, broad base of users (who just want to get something done and don't care about the techy stuff) needs lead-me-by-the-hand documentation (that goddamn well never even acknowledges the existence of a terminal window) for every package that might be installed by someone looking to move all their tasks from Windows to Linux. The stuff automagically and easily installable via the Ubuntu drop down is, IMO, the place to start. Poke around in there and you can find plenty of programs with docs that are crap, nonexistent, or next-to-impossible to find (which is just as bad as nonexistent).
The bad news: It may be difficult to jump onboard a specific project (particularly one as complex as Linux or Firefox) solely as a technical writer. Documentation ranges from extremely technical (as in code comments) to quite understandable (as in FAQs on websites). In my experience, the more technical documentation is left for the developers and the more understandable documentation is left for the admins.
The good news: If you're creative, you'll find a fulfilling way to help. If you're only interested in supporting a particular project, you could find its official discussion channel and work your way up to being a channel operator. If you're interested in the movement as a whole, you could contribute to a more generic (non-project-specific) documentation site. Many such sites even have author's guides where you can RTFM about WTFM (Writing The Firkin' Manual).
Good luck!
Raj Against the Machine! http://social-butterfly.appspot.com/
Here's a couple important projects that I've recently discovered are in *serious* need of better documentation:
1. GnuPG. I don't have any books on PGP or GPG, but the online documentation is horrendously incomplete and inexact.
2. RT (Request Tracker). There is a Wiki for documentation, but much of it is out of date and incomplete. The O'Reilly book is helpful, but there's a lot it doesn't cover.
I've been working with these two packages recently, so they're fresh in my mind. While you can glean quite a bit from the associated mailing lists for many open source and free software projects, it usually means wading through months if not years of posts in order to discover answers that may not even be corroborated.
With GnuPG, it took me quite a long time to find out that the secret key is still encrypted even when it's exported, though the existing documentation says that's it's insecure to export your secret key. How then, if that's insecure, are you supposed to share a single secret key among multiple computers? Most of the documentation doesn't even cover the possibility of doing this, and even the answer I found was embedded in some over-archingly insufferable responses from supposed experts "explaining" that security software shouldn't be used on untrusted systems. Well, as far as I'm concerned *all* systems should be considered untrusted to a certain extent, and this should be taken into account in the design of security software. So, phhhppppt. I also use a few Thawte certificates, and the built-in PKI mechanisms in most email and browser software simply works better from this perspective, anyway.
It also irks me that GnuPG support in such seminal projects as Thunderbird and Firefox needs to have extensions separately installed in order to function. That's not really helpful if I need to send a signed email to someone who doesn't know how to install and configure GnuPG or PGP and the necessary extensions.
Even if you can't do documentation, the most important thing you can do to improve free and open source software is to actually use the stuff, and report back to the developers on how the package does or does not fit your particular needs.
Some open source projects weclome content contributors, and this includes many things beyond coding. Writing up manuals/tutorials, providing artwork, finding and documenting bugs, making program content which doesn't require actual programming (interface skins, 3D models for games/sims, etc.)
Look for a suitable forum/wiki in regards to the open source project first, if one doesn't exist then contact the software developer(s) to see if they'd be willing to accept what you're offering.
Capcha: support
Which would explain why so many open source projects fail to get any traction with end users. I am no fan of Microsoft, but their documentation(in the form of the help menus) their Office line of products in my mind is excellent. I have found that many of the Office how-to books found on the shelves of Barnes and Noble are little more than rehashes of Microsoft's help files. You can't just throw code out and expect anyone but hardcore tech people to spend the time to figure out what a product does and how best to use it without producing some decent documentation.
On the other hand, a lot of closed-source, for profit software companies are guilty of this as well. The concept of the "Missing Manual" book series, is mind boggling. You buy a powerful piece of software, you should get a detailed manual explaining how to best use its functionality as part of the package.
"Lack of technical competence coupled with the arrogance of power, as usual, leads to no good end."
Here are a bunch of projects looking for doc writers on Source Forge. http://ask.slashdot.org/article.pl?sid=07/05/04/08 39241#topcomment
Talk to their developers. Most projects would love to have someone^W anyone working on documentation. Talking to them should hopefully give you an indication of a) what documentation they think would be useful, b) their willingness to accept any documentation that you write, and c) whether any such materials already exist that you could start from.
As a starting point, there are a few categories and types of user documentation that I believe all projects should have if they have any semblance of a community following:
Documentation is a particular aspect of a project that is particularly well suited to a BSD documentation license (a generalized version of the FreeBSD Documentation License) in terms of allowing completely unhindered distribution of content under very simple terms specific to documentation. Documentation benefits your user community no matter what form it exists in, commercialized or otherwise, yet also seems to be one of the hardest for open source projects to generate so making it as easy as possible to produce, modify, and redistribute (legally) is generally a very good thing.
Cheers!
Sean
Personally, I took an existing product with fairly good documentation (ndiswrapper) and dumbed it down for n00bs to intermediate SUSE Linux users. I explained the whole process of compiling from source, with pictures and everything. My hit counter and/or my GMail inbox is proof of the amount of people who've benefited.
So, if you're an advanced user, perhaps you could give back to the people who don't have a clue by taking existing docs designed for intermediate/advanced users and writing them for a less experienced audience.
~~ Andrew D.
It bothers me that everyone uses man, but so many man pages say, "This man page is incomplete; see the info page for complete details."
Shouldn't doc writers acknowledge that info hasn't displaced man and isn't likely to do so?
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've mostly noticed that this happens when you use man on the GNU tools. It appears the GNU standard is to use info rather than man, and the man page basically is an older revision. Info's nice, but it's a pain to navigate at the command line (it appears to be a severely stripped down version of Emacs). Wish it had a similar navigation style as lynx/links since info pages are really hypertext, and going back/forth can be painful. (info without a GUI is unusable for new users).
This is possibly the only major screwup in FOSS, that they tried to replace the extremely usable man page format by a different one that doesn't fulfil the same purpose. Info is not a replacement, it's a different thing altogether, good for more complex documents that require navigation, but FAR LESS USEFUL for the jobs where man pages shine so well, in other words where navigation is not needed, irritating, and NOT WANTED.
A very annoying step backwards. I'm all for info as additional documentation, but not as a replacement for man pages, because it simply isn't an equivalent functional replacement for man pages at all. Very bad.
When code is used for documentation, there's no way to determine if there are bugs.
Wikipedia seems a good place for contributing. You can start from simple format/typos editing or dive in full text editing.
And you can choose any topic, which is less constraining than programs only.
Documentation comes with maturity. Many [younger] free software projects move at such a pace (compare the Hagunenon evolution of Mozilla Thunderbird to the rock-steady Microsoft Outlook) that the documentation lags behind a version. Young projects have fewer users, and short intervals between releases with major changes, giving few man hours for the documentation to be updated. It's not yet in the developer's interest to produce complete accurate documentation; many intended features are yet to be introduced while current features are to be changed or removed completely.
Documentation is a target for/after the 1.0 release. A larger userbase of less experienced users demands complete documentation. Developers demand [API] documentation to allow extension. Major releases are rarer, more users have more time to complete documentation, for a stable feature-complete application.
This explains why no other project has documentation superior to perl's at perldoc. Check it out, it's exemplary.
http://perldoc.perl.org/
There's one or two programs that I would really like to be good with but their docs suck or don't exist. I've reached the age where I have a little money. I am actually considering hiring the developer to meet me on neutral ground and do a fresh install and walk-through while I film it, just so that I'll have the info I need to write real documentation. Then I'll sit down and start asking "How do I do this?"
After about 6 hours of that, I should know enough to write some docs or at least enough to use the software productively. I can't believe I'm contemplating spending, probably, thousands of dollars just to learn how to use some "free" software.
Oh, well. People pay till it hurts taking Photoshop classes, don't they?
Might I also suggest a look at Restructured Text as another alternative. Comes from the Python community. Raw text is a little easier to read IMHO and can also output to HTML, PS, PDF and LaTeX. Either way you go, one of these formats is nice in that you will easily be able to convert to most any format you'll need to publish your documentation in.
Then right a manual for that program as if you were explaining it to your mother/grandmother etc. I think its important that you understand the subject, or the use of the program very clearly yourself, in order to adequately explain its use and features. As well, understanding or enjoying the program will undoubtedly lead to a greater motivation when it comes to completing the documentation.
Bravo to you for even asking about getting involved. I find most companies I have worked for are remarkably disinclined to write adequate documentation. One of the places I am currently working at seems to view the lack of documentation for their softeware as a form of security from competitors, and since they also train clients in the use of it (very necessary mind you) its added encouragmeent for clients to pay for training. Overall though I think its a rediculous stupid attitude but they don't seem inclined to budge.
"The first time I got drunk, I got married. The second time I bought a chimpanzee, after that I stayed sober" Arian Seid
"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."
I think you phrased it perfectly. Man pages are extremely convenient for the writer, but not a particularly effective reference for the reader.
In perl's case, it gets across that its first priority is to be useful and honest, but not perfect or that its way is the right way to do things (e.g., 'you don't need stored procedures in a database, write your business logic in your code' vs. 'we don't have stored procedures yet; if you really need them, mysql may not be for you').
Since then, perl5 documentation has had contributions from multiple writers, so the writing styles can be a bit uneven. But they're still pretty good. Another important factor contributing to quality is that the module guidelines state that the documentation authoritatively specifies the module API and public/protected variable, etc distinction, not compiler- or language-enforced access controls. That kind of attitude encourages the documentation to have a certain level of clarity at the beginning.
So read the perl4 documentation. It's a good example. I personally would start by looking at man pages/docs that I've read, said 'oh man, this needs so much more information', and put the info in there. It's easy to justify the time on it when you have a personal stake because you're using the tools themselves; just jot down notes in complete sentences about actual usage, gotchas, etc, as you use the tool, and when you have a few free minutes, drop a note to the maintainer with a doc patch.
Mate: high 5 on wanting to help out. I'm a coder who doesn't contribute to existing projects (mostly due to time contraints and not for a lack of interest or desire) but releases the odd tool under a GPL or BSD license (or similar).
The lack of documentation in FLOSS aside (no flames please) you'd obviously be contributing to user documentation. I personally favour "complete" user documentation for a single system such as the FreeBSD Handbook (Gentoo and Debian have similar efforts). Of course even blogging HOWTOs may be useful to some one some day.
There are other ways to contribute. Hanging out on forums or IRC channels designed for helping end users in need is useful.
Have a look at any of the 100s of games and other applications written for the Linux desktop.
Have you tried Freeciv?
One of the best open source games ever. And one of the best documented, too.
Restructured Text doesn't seem to convert its input to man pages, which was the thrust of the OP's piece.
The last thing we need are yet *more* separate formats for presenting basic library and commandline information, we have more than enough already.
Man pages are extremely convenient for the writer, but not a particularly effective reference for the reader.
What's your planet like then? Does it rain purple-spotted toads when the jelly moths come out at moonfall?
My personal "gold standard" for docs is from the TCM project. This stands for "Toolkit for Conceptual Modeling", and includes diagram editors for UML, structured analysis, network diagrams, etc. You are expected to create custom editors for jobs not handled by the included tools.
Why is this a gold standard? Go to the project home page (currently http://wwwhome.cs.utwente.nl/~tcm), and look at the docs. First, they have both a user's guide and a developer's guide. The dev guide contains sections on system architecture (missing from almost ALL FOSS projects), source code organization, class hierarchy, and building.
So they tell you: 1) how the system is organized logically, and 2) how the source code is organized. Given this info, it's really easy to get in and work on the project.
On a more philosophical note: users can write user docs, programmers can write development docs. No user can write the dev docs, and programmers almost always suck at writing user docs. So figure out which one you are, and contribute in kind.
Your comment is as clear as a man page for a command you've never used before.
I was using UNIX all thru the 90's, and most of the time on a VT-220 text terminal. Then came X-terminals. I got a different GUI depending on host I loginnd to from my teminal, and the choice usually depended on finding one that's not overloaded. Customizing the commandline environment was easy (just define some aliases etc.) Customizing the GUI required more learning, but the worst part was that it broke whenever the GUI was changed. So I went to the helpdesk for help about using the default GUI I saw, but the usual answers were "that WM sucks. I use this one that's much better" and "RTFM" or actually check the man page. So I happily used "man" to look for different WMs and then used "man ...wm|lpr" to get them all printed so I can take it home and see what the options are and see what I want. But what I had was hundreds of pages listing options alphabetically, with no idea about what's important and what should be skipped. Eventually I gave up, and instead of using the Xterminal on my desk that was just working I brought my own heavy laptop with win95 preinstalled and miles of ethernet cables, conected to the network, and didn't have to RTFM.
man pages were nice in the old days of not too many options, but you cannot call them "help" when they list thousands of options with descriptions that can only be comprehended by people who know the inner working of the OS or the describes software, that are prioritised based on alphabetical order of the option's code (which was often chosen based on what letters remained available at the time the option was added.
man pages are good for developers. For years I was trying to switch to using LINUX on the desktop, but I don't have infinite time, and to this time most trials I made were failures, though not completely unuseful. And it's not that I born in the Windows environment. I was using Unix when it was just commandline and someone else did the system maintenance.
What Linux/FOSS needs is a standard way to cooperate on writing documentation and prioritising it, and to recruit people who are not developers into writing documentation without having to first learn how to do it. SOmething that none technical people can easily use to contribute.
You can learn how to create good documentation by learning to create DOCUMENTATION. Essentially, what you're asking here is how to be a good technical writer. One of the best ways to do this is to learn about the software engineering process. You won't necessarily have to learn how to program, but you will probably end up learning a little UML (Unified Modeling Language).
In the Unified Process (and many other software engineering methodologies) a technical writer/architect/project manager will create documentation to describe the problem and a potential solution (i.e. the design for a piece of software) to programmers, customers, and upper management. In fact 'working the documentation process' is a sound part of software engineering. One of the methods implored is to create a set of 'use cases'. A use case is a description of the actions on a system/piece of software. Often use cases (documented actions on the system) provide a great template for a user manual.
Books on how to write use cases:
Writing Effective Use Cases
by Alistair Cockburn
Use Case Modeling
by Kurt Bittner, Ian Spence
A book on how to create requirements documents (i.e. creating documentation):
Managing Software Requirements: A Use Case Approach
by Dean Leffingwell, Don Widrig
A book on the Unified Process and Software Engineering (from Analysis to Code):
Applying UML and Patterns: An Introduction to Object-Oriented Analysis and Design and Iterative Development
by Craig Larman
What do you mean my sig is repetitive? What do you mean my sig is repetitive? What do you mean....
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.