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?"

RTFM on writing documentation

[Timesprout]

Oh wait....

Re:

[Anonymous Coward]

shouldn't it be W(rite)TFM? WTFM, dude.

Re:RTFM on writing documentation

[laejoh]

You sig inspires me!

Do not try to read the documentation--thats impossible. Instead, only try to realize the truth

What truth?

There is no documentation

Sad actually...

Re:RTFM on writing documentation

[Enry]

Err...actually...you can RTFM on how to write documentation. I should know - I wrote one:

LDP Author Guide [tldp.org]

Re:

[xero314]

you can RTFM on how to write documentation. I should know - I wrote one.

Does it say "Make sure you do your best to make any Open Source Documentation as incomplete and spotty as possible, and contains barely enough information to make the end user think he's stupid when he can install, execute, and/or extend to software."

Re:

[8-bitDesigner]

Pish, the LDP is damned good, if just a bit dated. Also, Gentoo has some awesome documentation and a very dedicated doc-writing team. The distro's not so hot, but if this bloke wants to contribute, they're a good start.

Uhhh.. just do it?

[QuantumG]

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.

Re:Uhhh.. just do it?

[Timesprout]

Contact that person, offer to write a help page, they'll tell you how.

You would like to think so but the reality is more likely is they will tell you get lost because since they didn't have the time/inclination to write the documentation in the first place they are unlikely to be able or willing to find time to hold your hand through explaining it all to you. Developers round here, myself included tend to attempt disappearing tricks when we see the technical writers heading in our direction.

Re:

[JohnFluxx]

Speak for yourself. I'm sure most developers more than welcome someone to do the writing for them, myself included.

Re:

[Timesprout]

Yes but the point is the documentation usually doesn't just happen without the developer spending time either explaining it to a writer or typing it themselves and most developers tend to be unwilling to engage in either of these activities.

No wonder so many OSS projects get ignored

[Scott7477]

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

Re:

[karolo]

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.

Getting developer support

[BenEnglishAtHome]

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

Re:

[Raenex]

Lots of stuff you can figure out on your own just by experimenting. Anything else you can ask on a mailing list.

Re:

[BenEnglishAtHome]

Lots of stuff you can figure out on your own just by experimenting. Anything else you can ask on a mailing list.

Learning to use software should not be a process of reverse-engineering; it should be (at least in the beginning) a linear task guided by provided documentation that, at minimum, covers the base install and most common, core function of the software. Yes, I can figure a lot of things out. Here's an example: I'm using a program that saves files to a default location. When you save a file, a di

Re:

[jgrahn]

Speak for yourself. I'm sure most developers more than welcome someone to do the writing for them, myself included.

Speak for yourself. I prefer doing my own documentation, because it helps me understand my features and my user interface. Also, if I don't do it, the documentation will be badly written or incorrect, and the users will come and bother me with silly questions and I will be unable to tell them to RTFM.

Re:

[Wordplay]

So where's "round here"? I don't think I want to work anywhere where developers have that grossly exaggerated of a sense of entitlement. There's an entire process that you're just a cog in, you know. If nobody understands your software, your work is worse than useless. Its presence will discourage people from starting actually-usable projects that would have done the same thing.

Re:

[xero314]

I don't think I want to work anywhere where developers have that grossly exaggerated of a sense of entitlement.

The you pretty much want to stay away for most Open Source projects. I have yet to meet an Open Source project lead (not just someone that commits to a project) that doesn't have an exaggerated sense of entitlement. This is why the documentation sucks in general. Notice I said most, and I haven't met. Yes there are some decent OSS projects that actually document their work, but these are few and far between.

Re:

[jgrahn]

The you pretty much want to stay away for most Open Source projects. I have yet to meet an Open Source project lead (not just someone that commits to a project) that doesn't have an exaggerated sense of entitlement. This is why the documentation sucks in general. Notice I said most, and I haven't met. Yes there are some decent OSS projects that actually document their work, but these are few and far between.

Exactly which projects are you talking about? Because I use exclusively open source programs at hom

Re:

[dhasenan]

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 forma

Re:

[bit01]

You would like to think so but the reality is more likely is they will tell you get lost

Nonsense, an insulting and meaningless generalization.

The actual reality is that every developer is different, most developers enjoy the attention their projects attract and while they might not help a lot due to time constraints they are likely to at least point somebody like this in the right direction.

---

You communist! Breathing shared air!

Re:

[tepples]

Notice the only thing there is "About".. which is really helpful when it comes to figuring out how you play this puzzle game.

That is, unless "About" or the package's README file gives the URL of a help page on the web that explains the game mechanics. I try to do that for my own free puzzle games such as Luminesweeper [pineight.com] and LOCKJAW [pineight.com]. Or is it that you are trying to learn the game while commuting?

Re:

[QuantumG]

Heh, not everyone has connectivity dude.

Yeah, sometimes I like to play little puzzle games when I'm disconnected from the net.

When I'm connected to the net, I typically find something a lot more interesting to do.

Re:

[stevey]

That is one approach - writing documentation for games/software, and trying to get it included in the future releases.

Another approach is to start writing guides on how to use software, configure it, etc. Then submit that documentation to the appropriate forums and wikis.

I started a site [debian-adm...ration.org] aimed at documentation useful for Debian, which is nothing more than a collection of individual articles on a few topics. Despite that it has been very useful to myself and others. I'm not suggesting you setup your own

Re: Freeciv

[lieutenant_Zaz]

Have a look at any of the 100s of games and other applications written for the Linux desktop.

Have you tried Freeciv [freeciv.org]?

One of the best open source games ever. And one of the best documented, too.

FOSS needs Documentation fast

[hellsDisciple]

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.

Re:

[xtracto]

The must funny piece of documentation I have seen was in a *released* KDE piece of documentation for some main program (dont remember exactly which now but it was not a game or a minor K-app), were all the headings were written but when you actually went to read the content of the section you could only find something like:

This section needs to be extended or
Please write something here...

I an only imagine if while surfing through Microsoft SQL documentatino I find something like that... terrible, so much f

Re:

[try_anything]

You can always fill in a section with something useless.

I remember in school that teachers gave much better grades for a bit of empty blabbing than for a missing answer. I assume that commercial doc writers are held to much the same standard.

A blank section might look worse, but at least it's honest.

Re:

[Kickersny.com]

Perhaps you're thinking of KDevelop. [kde.org] Much of the User Manual [kde.org] is missing. Here's an example: http://docs.kde.org/development/en/kdevelop/kdevel op/ui-elements.html [kde.org]

Re:

[jgrahn]

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.

Ridiculous. Man pages are the standard documentation for Unix programs. If people refuse to read those (a matter of typing the word "man") it's their problem.

A Linux distribution which wants to be really user-friendly could easily include a web interface which provi

Why I stopped using UNIX

[hadaso]

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

Anwyhere you like

[LarsWestergren]

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 [amazon.com]. 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 [wikibooks.org] 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.

3 cheers for this guy

[simm1701]

Just remember:

Documentation is like sex, when its good, its very very good, and when its bad its better than nothing.

Never mind that

[DaveCar]

I'm an Open Source guy that runs Linux

Wow! He should document himself.

Re:3 cheers for this guy

[Wordplay]

Ah, that explains why I'm the only one who ever reads my documentation.

Re:

[nacturation]

Your controls are so user friendly, you're self-documenting?
 

Re:

[pnutjam]

I see you and raise you "The only thing worse then no documentation is bad documentation."

Have you ever bought a car part and were given the wrong one? I have, sometime car parts look different due to minor redesigns so I assume that is the case and try to fit that damn part on, rarely do I succeed, but I sure waste a hell of a lot of time.

Re:

[simm1701]

"A bug in the comments/documentation is worth 2 in the code"

Re:

[TuringTest]

Code tells the "how". Good documentation (including code comments) must tell the "why"; the programmer's intent is something that cannot be captured by a programming language.

Re:

[try_anything]

Luckily, many open source projects are developed using a methodology called "Illiterate Programming," where code and documentation are interleaved. Illiterate programming is very simple and only uses two commands, cat and echo.

To access the code for a source file, use the "cat" command:

cat foo.c
cat foo.c | gcc -o foo

To see the code documentation for the file, you also use the echo command:

echo 'See foo.c'

To see the user documentation, use the cat command:

cat /dev/null

Perhaps that accounts for the buggy code

[ClosedSource]

When code is used for documentation, there's no way to determine if there are bugs.

First steps to get you started

[fiffilinus]

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 [icsharpcode.net] 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

Find a friendly project

[albalbo]

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.

Re:

[dhasenan]

Record everything you explain to them. That way, as long as what you say doesn't go out of date, you only have to find what you wrote.

And, hey, slap an index on it and you can call it your documentation.

Re:

[Rakshasa Taisab]

I was going to write something similar to this. My project is pretty much a one-man-show and over the past year has become somewhat popular. Getting tons of user-support mails, bad and duplicate bug reports, etc, has conditioned me into just ignoring/close anything that doesn't look like a useful question/report.

If someone were to offer to help write documentation, they should started writing something and ask questions not easily found in what is available of documentation. This would show that the person

Examples?

[TheRaven64]

What are some stellar examples?

OpenBSD. Hands-down, the best documentation of any F/OSS project I've ever used. The man pages for every command, file, or device are detailed and complete. Any code change that alters an interface and doesn't come with a corresponding update to the documentation is not allowed in the tree. If you want to see how documentation should be done, install OpenBSD.

Re:

[amper]

Documentation being complete and detailed does not necessarily translate into easy to read and easy to follow for users less knowledgeable than a dyed-in-the-wool guru. This is the main failing of even the best documentation I've seen out there. Not enough time is spent on step by step directions, and not enough time is spent discussing the ramifications of particular configuration options. Much of the time, the user is expected to already know what a particular option does...which obviates the need for doc

Re:

[Clover_Kicker]

Documentation being complete and detailed does not necessarily translate into easy to read and easy to follow for users less knowledgeable than a dyed-in-the-wool guru.

Sure, but consider OpenBSD's target audience.

This is the main failing of even the best documentation I've seen out there. Not enough time is spent on step by step directions, and not enough time is spent discussing the ramifications of particular configuration options. Much of the time, the user is expected to already know what a particular option does...which obviates the need for documentation in the first place.

You're totally correct, unfortunately this is also true for 99% of commercial software.

Writing good documentation is hard, that's why it's so rare.

Re:

[azrider]

Having taught many courses (including Solaris administration), might I also suggest that you get involved with your local LUG? By helping new users (and making notes of what they ask), you will get a feel for those things which are *obvious* to you (now..) but not to someone new to the *nix way (ie: the temporary files usually are stored in tmp not temp).

Re:

[Richard_at_work]

I would actually recommend the PHP documentation as well - while the language itself leaves much to be desired, I have yet to find another project or language that provides concise, easy to read and useful documentation as the PHP website does - its simply brilliant.

Re:

[Kalzus]

Just personal experience, but you might try the Python documentation. Class organization, an index, and a useful tutorial to boot.

Re:

[MountainLogic]

Style, needs and perceived quality change over time, but the only manuals I remember opening and thinking WOW! were the Apple manuals from the //e and GS era.

Re:

[Raenex]

Amiga 4ever!!

Easy start to documentation: write man pages

[Morgaine]

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 [cpan.org] and the POD [wikipedia.org] 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 [sf.net] suite too, which is very handy.

The Doxygen [sf.net] 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.

Re:

[try_anything]

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?

Re:

[tlhIngan]

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?

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

Re:

[BigJimSlade]

Might I also suggest a look at Restructured Text [sf.net] 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.

Re:

[ClosedSource]

"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.

Re:

[ClosedSource]

Your comment is as clear as a man page for a command you've never used before.

The weak link of open source

[smchris]

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

PHP Manual

[ergonal]

The PHP Documentation Team is always looking for contributors. For an easy start, you could help by documenting undocumented functions [php.net], for example..

http://www.tldp.org/

[ChaseTec]

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.

Usenet apps (just to illustrate a point)

[BenEnglishAtHome]

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 Pa

Re:

[elrous0]

The problem with a lot of OSS (and I'm running 7.04 at home too) is that developers are so obsessed with adding new features, fixing bugs, etc. that it never occurs to them that documentation is JUST as important as the coding. You can have a million features, but if no one else but you knows how to use them, they may as well not even exist.

On *MANY* OSS projects, their webpage tells the tale. A huge page of "latest updates" and "bug fixes" with absolutely no page that tells WHAT THE SOFTWARE ACTUALLY IS

Re:

[try_anything]

That's an excellent point. I personally like the old web site formula, which I don't see much these days, of designing the default front web page for total noobs and making another front page for regular visitors. Beginners looking for help end up at the right place, and regular visitors bookmark the news and updates page.

Specific Project or Movement as a Whole?

[Brainix]

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 intere

Some projects seriously in need!

[amper]

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 f

Re:

[CronoCloud]

1. GnuPG. I don't have any books on PGP or GPG, but the online documentation is horrendously incomplete and inexact.

Oh it's not too bad, the Mini-Howto is enough to get started:

http://webber.dewinter.com/gnupg_howto/english/GPG MiniHowto.html [dewinter.com]

However, try to find documentation on how to use the GUI frontends, like GPA. The documentation I've seen for the Windows users even new ones, pretty much ignores it and goes to the command line They should be telling people who aren't console cowboys to be using that

Go for you!

[Pond823]

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 [slashdot.org]

Start with the basics

[morrison]

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 comm

Dumb It Down

[andrewd18]

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

Re:

[CronoCloud]

Great idea!

Though some projects out there don't have good enough documentation for even advanced users to figure out how to use them.

For good docs, pretend you're a newbie; eg GnuCash

[KWTm]

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.)

Documentation comes with maturity

[matt me]

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 introduce

And some people just have what it takes

[Krishnoid]

I've been writing perl for 15 years now, but what attracted me to it originally was the perl 4 documentation. That's my best example of friendly, nonpedantic documentation. In fact, I tell everybody that what attracted me to the language was the way design decisions and suggested usage was clearly expressed in the documentation. It made me think, if the *documentation* is this clearly thought out, software that it represents will be of comparable quality. It's sort of like seeing someone in the parking

Find a Program/Subject You Understand Clearly

[Phrogman]

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 disincline

Awesome

[noz]

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 [freebsd.org] (Gentoo [gentoo.org] and Debian [debian.org] have similar efforts). Of course even blogging

Learn how to create 'Use Cases'

[1iar_parad0x]

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 docu

Consider posting a checklist

[StephenNorthcutt]

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 [sans.org], just drop me a note.