×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Writing Open Source Documentation?

Cliff posted more than 6 years ago | from the open-source-needs-more dept.

Programming 92

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

cancel ×
This is a preview of your comment

No Comment Title Entered

Anonymous Coward 1 minute ago

No Comment Entered

92 comments

RTFM on writing documentation (4, Funny)

Timesprout (579035) | more than 6 years ago | (#18985753)

Oh wait....

Re:RTFM on writing documentation (3, Funny)

Anonymous Coward | more than 6 years ago | (#18985847)

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

Re:RTFM on writing documentation (5, Funny)

laejoh (648921) | more than 6 years ago | (#18986287)

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 (4, Informative)

Enry (630) | more than 6 years ago | (#18986469)

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

LDP Author Guide [tldp.org]

Re:RTFM on writing documentation (1)

xero314 (722674) | more than 6 years ago | (#18989599)

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:RTFM on writing documentation (1)

8-bitDesigner (980672) | more than 6 years ago | (#18990175)

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? (2, Insightful)

QuantumG (50515) | more than 6 years ago | (#18985825)

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? (3, Interesting)

Timesprout (579035) | more than 6 years ago | (#18985883)

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:Uhhh.. just do it? (1)

JohnFluxx (413620) | more than 6 years ago | (#18986085)

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

Re:Uhhh.. just do it? (1)

Timesprout (579035) | more than 6 years ago | (#18986199)

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 (1)

Scott7477 (785439) | more than 6 years ago | (#18987501)

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.

Re:No wonder so many OSS projects get ignored (2, Informative)

karolo (595531) | more than 6 years ago | (#18988349)

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 (1)

BenEnglishAtHome (449670) | more than 6 years ago | (#18990795)

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?

Re:Getting developer support (1)

Raenex (947668) | more than 6 years ago | (#19006819)

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

Re:Getting developer support (1)

BenEnglishAtHome (449670) | more than 6 years ago | (#19021537)

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 dialog pops up to confirm that location and I certainly know enough to type in a different path if I want to store the file in a different location. This is nothing I need help with but I found the defaults irritating; different files should, by convention, be stored in different places depending on their origin and/or type. This program wanted me to just dump everything in one place. Just for the hell of it, I hit the "Help" button. I didn't expect anything. After all, only a total newbie (and I don't mean that in a pejorative sense in any way in this case) needs help on how to specify a directory to save a file. So I expected to see something basic like "Type in a different location if you want to save to some non-default location". What did I find? A quick explanation of various command-line variables that I could insert into the file path to creat new directories automatically depending on what I was saving. That was great! It was just what I needed and more! But was that basic info in a FAQ? No. Was it mentioned under a "preferences" dialog somewhere? No. Was it in the official documentation? No, because there isn't any. Was it findable under "Help" from the top-line menu? No, because that menu item doesn't do squat. I would expect to find help at any of those four places in addition to the "help" button in the dialog. Instead, the documentation for this feature is found in only 1 of the 5 places it could reasonably be placed.

So maybe the docs exist. Maybe I just need to hit every help button I ever see in this program. I'm in the process of doing that right now.

But, y'know, I just can't help feeling that this trip really isn't necessary.

As for asking on a mailing list - OK, I can try that. To be a good list subscriber, however, I should first read the list archives so I don't re-ask common questions. Oh, wait, there don't seem to be any archives. I guess I'll just be quiet on the list for a good long while so I don't look stupid and get yelled at.

I'm going to stand by my original, most basic point. Good docs are important and there are far more OS projects with excreble or nonexistent docs than there are with good ones.

Re:Uhhh.. just do it? (1)

jgrahn (181062) | more than 6 years ago | (#18999849)

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:Uhhh.. just do it? (0)

Anonymous Coward | more than 6 years ago | (#18986297)

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

I actually don't think that happens very often. But of course, if it does, find another project with more mature developers. Your contributions will be appreciated there.

For a laugh, a couple of years later you can check out the blog entries of the first developer. There you will see where he writes long bitter rants about how stupid everyone else is, and how no one uses or cares about his fantastic l337 Lisp application, and how he is thinking about giving up on the computer industry all together.

Re:Uhhh.. just do it? (1)

Wordplay (54438) | more than 6 years ago | (#18986519)

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:Uhhh.. just do it? (1)

xero314 (722674) | more than 6 years ago | (#18989733)

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:Uhhh.. just do it? (1)

jgrahn (181062) | more than 6 years ago | (#18999863)

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 home, and the only ones with sucky documentation that come to mind are the Linux kernel, udev, ntp, gnuplot, gtk and ... no, those are the only ones.

Maybe it's those fancy Gnome programs that have sucky docs? I don't use those.

Re:Uhhh.. just do it? (2, Informative)

dhasenan (758719) | more than 6 years ago | (#18986551)

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.

Re:Uhhh.. just do it? (2, Insightful)

bit01 (644603) | more than 6 years ago | (#18986877)

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:Uhhh.. just do it? (1)

tepples (727027) | more than 6 years ago | (#18987123)

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:Uhhh.. just do it? (1)

QuantumG (50515) | more than 6 years ago | (#18987605)

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:Uhhh.. just do it? (1)

stevey (64018) | more than 6 years ago | (#18988061)

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 site and fragment things further, but I'm sure there are markets for many beginner-level (and more advanced) introductions to particular software applications and packages.)

Re: Freeciv (1)

lieutenant_Zaz (938416) | more than 6 years ago | (#18997947)

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 (3, Informative)

hellsDisciple (889830) | more than 6 years ago | (#18985833)

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:FOSS needs Documentation fast (1)

xtracto (837672) | more than 6 years ago | (#18986467)

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 for RTFM no?

Re:FOSS needs Documentation fast (1)

try_anything (880404) | more than 6 years ago | (#18987671)

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:FOSS needs Documentation fast (1)

jgrahn (181062) | more than 6 years ago | (#18999927)

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 provides an index, searching, and PDF+HTML versions of all man pages on the system. (Hmm... nice idea. Maybe I'll write one tonight.)

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.
/usr/share/doc/package is the standard place for non-manpage documentation in most or all Linux distribution. How is that being "buried"? Point your browser to file:///usr/share/doc/ and it's all there.

Why I stopped using UNIX (1)

hadaso (798794) | more than 6 years ago | (#19009261)

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.

Anwyhere you like (5, Interesting)

LarsWestergren (9033) | more than 6 years ago | (#18985849)

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 (5, Funny)

simm1701 (835424) | more than 6 years ago | (#18985869)

Just remember:

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

Re:3 cheers for this guy (1)

laejoh (648921) | more than 6 years ago | (#18986389)

Hey, this is slashdot! How would he remember about something called sex (Software EXchange?)

It does mean Software EXchange, no?

Re:3 cheers for this guy (1)

pnutjam (523990) | more than 6 years ago | (#18992649)

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.

Open source software is already documented (0)

Anonymous Coward | more than 6 years ago | (#18985885)

Just look for the files with .c and .h extensions.

Re:Open source software is already documented (1)

TuringTest (533084) | more than 6 years ago | (#18986317)

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:Open source software is already documented (1)

try_anything (880404) | more than 6 years ago | (#18987885)

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 (1)

ClosedSource (238333) | more than 6 years ago | (#18989555)

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

Advice (0, Redundant)

Anonymous Coward | more than 6 years ago | (#18985893)

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)

First steps to get you started (2, Informative)

fiffilinus (45513) | more than 6 years ago | (#18986017)

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 is the best guide out there, but it is decent for getting started into technical writing.

Find a friendly project (2, Informative)

albalbo (33890) | more than 6 years ago | (#18986029)

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.

Make sure you follow through (0)

Anonymous Coward | more than 6 years ago | (#18986229)

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.

Re:Make sure you follow through (1)

dhasenan (758719) | more than 6 years ago | (#18986611)

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:Make sure you follow through (1)

Rakshasa Taisab (244699) | more than 6 years ago | (#18987715)

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 really is willing to try, and it gives an opportunity to comment on the format of the document.

Examples? (3, Informative)

TheRaven64 (641858) | more than 6 years ago | (#18986307)

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:Examples? (1)

amper (33785) | more than 6 years ago | (#18986955)

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 documentation in the first place.

Re:Examples? (1)

Clover_Kicker (20761) | more than 6 years ago | (#18987683)

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:Examples? (2, Informative)

azrider (918631) | more than 6 years ago | (#18987727)

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:Examples? (1)

Richard_at_work (517087) | more than 6 years ago | (#18988199)

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:Examples? (1)

Kalzus (86795) | more than 6 years ago | (#18991041)

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

Easy start to documentation: write man pages (4, Informative)

Morgaine (4316) | more than 6 years ago | (#18986333)

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:Easy start to documentation: write man pages (1)

try_anything (880404) | more than 6 years ago | (#18987957)

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:Easy start to documentation: write man pages (1)

tlhIngan (30335) | more than 6 years ago | (#18989273)

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

info--, man pages++ (0)

Anonymous Coward | more than 6 years ago | (#18989313)

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?
Yes indeed, very well said!

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.

Re:Easy start to documentation: write man pages (1)

BigJimSlade (139096) | more than 6 years ago | (#18992433)

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:Easy start to documentation: write man pages (0)

Anonymous Coward | more than 6 years ago | (#19000447)

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.

Re:Easy start to documentation: write man pages (1)

ClosedSource (238333) | more than 6 years ago | (#18993639)

"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:Easy start to documentation: write man pages (0)

Anonymous Coward | more than 6 years ago | (#19000629)

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?

Re:Easy start to documentation: write man pages (1)

ClosedSource (238333) | more than 6 years ago | (#19007277)

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

The weak link of open source (1)

smchris (464899) | more than 6 years ago | (#18986479)

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.

   

PHP Manual (1)

ergonal (609484) | more than 6 years ago | (#18986529)

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

Re:PHP Manual (0)

Anonymous Coward | more than 6 years ago | (#18986757)

Now, I'd like to give back, but the problem is that I'm not a coder.

Now, I'd like to give back, but the problem is that I'm not a coder.

Now, I'd like to give back, but the problem is that I'm not a coder.

http://www.tldp.org/ (1)

ChaseTec (447725) | more than 6 years ago | (#18986583)

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) (1)

BenEnglishAtHome (449670) | more than 6 years ago | (#18986651)

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

Re:Usenet apps (just to illustrate a point) (1)

elrous0 (869638) | more than 6 years ago | (#18987017)

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 AND DOES. The top heading of the first page of your software's (call it XX) webpage shouldn't say "Latest XX Updates." It should say "What is XX?" followed by a basic explanation of what it is and does. And the "Documentation" page shouldn't lead to a bulletin board or a FAQ. It should lead to a short basic introduction to the user interface and basic features of the software (you can pad it out more later, but start with the basics). If you don't have these basics, then you need to stop developing new features and bug fixes and write some documentation instead.

Re:Usenet apps (just to illustrate a point) (1)

try_anything (880404) | more than 6 years ago | (#18988083)

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? (1)

Brainix (748988) | more than 6 years ago | (#18986797)

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 [freenode.net] 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 [tldp.org]. Many such sites even have author's guides [tldp.org] where you can RTFM about WTFM (Writing The Firkin' Manual).

Good luck!

Some projects seriously in need! (1)

amper (33785) | more than 6 years ago | (#18986873)

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.

Re:Some projects seriously in need! (1)

CronoCloud (590650) | more than 6 years ago | (#18995523)

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, and no listing the icons is not enough.

You'll also see the mutt-GPG howto, but very little for integrating GPG in email programs that "ordinary people" actually use. (Yes I have mutt installed, but I use Claws Mail, thank goodness they have good documentation)

I had the devil of the time myself just generating my key using the command line (not enough entropy), but GPA worked.

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?


Technically you're supposed to have a separate secret key for yourself on the other box, but that's just annoying if you want to decrypt your own stuff on another box. I just transferred my secret key over and use one on both.

Is there a forum or wiki? (0)

Anonymous Coward | more than 6 years ago | (#18986887)

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

Start with the basics (1)

morrison (40043) | more than 6 years ago | (#18987797)

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:

  • README - Essential overview documentation, for new users that download a source and/or binary distribution
  • INSTALL - Instructions on how to install a source and/or binary distribution
  • AUTHORS - A historical reference of who worked on what and when (often requires extensive research for larger projects)
  • HACKING - Contributor documentation, how to make contributions to the project, conventions established, submission requirements
  • COPYING - Legal documentation, hopefully something more than the license(s), an explanation of the legal requirements
  • Manual Pages
    • Commands - There should be a overview and usage page for every command installed (sections 1, 6, & 8)
    • Libraries - There should be a summary overview page for every library installed (section 3)
    • File formats - If the app(s) have their own file formats, each format should be a page that describes the format (section 5)
  • Overview - Goes into more depth than the README information about the project and functionality provided
  • Tutorial(s) - At least one tutorial showing how to use the software

Documentation is a particular aspect of a project that is particularly well suited to a BSD documentation license [sourceforge.net] (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.

Dumb It Down (1)

andrewd18 (989408) | more than 6 years ago | (#18987801)

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.

Re:Dumb It Down (1)

CronoCloud (590650) | more than 6 years ago | (#18995555)

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 (2, Insightful)

KWTm (808824) | more than 6 years ago | (#18988173)

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

Wikipedia (0)

Anonymous Coward | more than 6 years ago | (#18989753)

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 (1)

matt me (850665) | more than 6 years ago | (#18989799)

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

And some people just have what it takes (1)

Krishnoid (984597) | more than 6 years ago | (#18996489)

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 lot step up and help an old lady carry her groceries to her car while everybody else just walks by. You gain confidence that there's a certain level of quality/civility you can count on even if you're not sure about external appearances.

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.

Find a Program/Subject You Understand Clearly (1)

Phrogman (80473) | more than 6 years ago | (#18992515)

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.

Awesome (1)

noz (253073) | more than 6 years ago | (#18996861)

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

Best Docs I've Ever Seen (0)

Anonymous Coward | more than 6 years ago | (#19005475)

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 [utwente.nl]), 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.

Learn how to create 'Use Cases' (1)

1iar_parad0x (676662) | more than 6 years ago | (#19009327)

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 [amazon.com]
by Alistair Cockburn

Use Case Modeling [amazon.com]
by Kurt Bittner, Ian Spence

A book on how to create requirements documents (i.e. creating documentation):
Managing Software Requirements: A Use Case Approach [amazon.com]
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 [amazon.com]
by Craig Larman

Consider posting a checklist (2, Interesting)

StephenNorthcutt (1100085) | more than 6 years ago | (#19060411)

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.
Check for New Comments
Slashdot Account

Need an Account?

Forgot your password?

Don't worry, we never post anything without your permission.

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>
Sign up for Slashdot Newsletters
Create a Slashdot Account

Loading...