Writing Open Source Documentation? 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?"
RTFM on writing documentation (Score:5, Funny)
Re: (Score:3, Funny)
Re:RTFM on writing documentation (Score:4, Funny)
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 (Score:5, Informative)
LDP Author Guide [tldp.org]
Re: (Score:2)
Re: (Score:1)
Uhhh.. just do it? (Score:3, Insightful)
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? (Score:4, Interesting)
Re: (Score:2)
Re: (Score:2)
No wonder so many OSS projects get ignored (Score:2)
Re: (Score:2, Informative)
Getting developer support (Score:2)
After about 6 hours of that, I should know enough to write some docs or at least enough to use the
Re: (Score:2)
Re: (Score:2)
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: (Score:2)
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: (Score:2)
Re: (Score:2)
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: (Score:2)
Exactly which projects are you talking about? Because I use exclusively open source programs at hom
Re: (Score:3, Informative)
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: (Score:3, Insightful)
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: (Score:1)
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: (Score:2)
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: (Score:1)
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 (Score:1)
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 (Score:3, Informative)
Re: (Score:2)
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: (Score:2)
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: (Score:1)
Re: (Score:2)
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 (Score:1)
Anwyhere you like (Score:5, Interesting)
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 (Score:5, Funny)
Documentation is like sex, when its good, its very very good, and when its bad its better than nothing.
Never mind that (Score:1, Troll)
Wow! He should document himself.
Re:3 cheers for this guy (Score:4, Funny)
Re: (Score:2)
Re: (Score:2)
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: (Score:2)
Re: (Score:2)
Re: (Score:2)
To access the code for a source file, use the "cat" command:
To see the code documentation for the file, you also use the echo command:
To see the user documentation, use the cat command:
Perhaps that accounts for the buggy code (Score:2)
First steps to get you started (Score:2, Informative)
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 (Score:3, Informative)
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: (Score:2)
And, hey, slap an index on it and you can call it your documentation.
Re: (Score:2)
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? (Score:4, Informative)
Re: (Score:2)
Re: (Score:2)
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: (Score:2, Informative)
Re: (Score:2)
Re: (Score:2)
Re: (Score:2)
Re: (Score:2)
Easy start to documentation: write man pages (Score:5, Informative)
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: (Score:2)
Shouldn't doc writers acknowledge that info hasn't displaced man and isn't likely to do so?
Re: (Score:2)
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: (Score:2)
Re: (Score:2)
I think you phrased it perfectly. Man pages are extremely convenient for the writer, but not a particularly effective reference for the reader.
Re: (Score:2)
The weak link of open source (Score:2)
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 (Score:2)
http://www.tldp.org/ (Score:2)
Usenet apps (just to illustrate a point) (Score:2)
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: (Score:2)
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: (Score:2)
Specific Project or Movement as a Whole? (Score:2)
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! (Score:2)
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: (Score:2)
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! (Score:1)
Start with the basics (Score:1)
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 (Score:1)
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: (Score:2)
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 (Score:3, Insightful)
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 (Score:2)
And some people just have what it takes (Score:1)
Find a Program/Subject You Understand Clearly (Score:2)
Bravo to you for even asking about getting involved. I find most companies I have worked for are remarkably disincline
Awesome (Score:2)
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' (Score:1)
In the Unified Process (and many other software engineering methodologies) a technical writer/architect/project manager will create docu
Consider posting a checklist (Score:2, Interesting)