Have you ever noticed that the communities where you’re told the most frequently to RTFM - Read The F* Manual - are the same ones where that manual is likely to be awful? I believe that this is, in fact, not merely correlation, but also causation - that is, the attitude results in the poor docs.
There’s a few commonly held beliefs about documentation for software, and in particular open source software: 1) It’s awful, 2) Nobody ever wants to write it. 3) That’s just the way things are, and we can’t do much about it.
The reality, however, is that there are lot of people that want to write documentation, and we, the gatekeepers of open source projects, just make it too hard for them to do it. We put up artificial social barriers. (For example, the myth that documentation is a somehow less important contribution than “real” code.) We put up strange workflows. (Get a checkout. Make your changes. Make a diff. Subscribe to a mailing list. Send the diff to the list.Get told that it’s against the wrong version, and can you make the patch again. etc.) We write our documentation in arcane formats (Docbook, LaTeX, Asciidoc) that people have to first learn before they can tell you misspelled a word.
But to see that people are anxious to write documentation, you only have to look at sites like StackOverflow, as well as the numerous topic-specific websites put up by various individuals who didn’t want to jump through all the hoops to write official documentation. Some of these sites are great. Others are grossly out of date. Still others recommend “solutions” that are not best practice, or, in some cases, are actually harmful. Additionally, it creates confusion for the users of the software, who aren’t sure which site they need to be getting their authoritative information from, when they encounter differing advice.
In his first “State of the Onion” address, Perl creator Larry Wall defined the three virtues of a programmer - Laziness, Impatience, and Hubris”
Laziness: The quality that makes you go to great effort to reduce overall energy expenditure. It makes you write labor-saving programs that other people will find useful and document what you wrote so you don't have to answer so many questions about it. Impatience: The anger you feel when the computer is being lazy. This makes you write programs that don't just react to your needs, but actually anticipate them. Or at least pretend to. Hubris: The quality that makes you write (and maintain) programs that other people won't want to say bad things about.
However, in his second State of the Onion, he went on to clarify that while these are the virtues of an individual, they are the opposite of the virtues of a community, or of a person.
Laziness, Impatience, and Hubris in people beget arrogance and rudeness when beginners come to your mailing list, IRC channel, or other discussion venue, and ask what you perceive to be stupid questions. It also leads to documentation that is incomplete, untested, and disrespectful to the people whose only crime is knowing less than you do.
On the other hand, diligence, patience and humility result in treating the user - the questioner - the customer, if you will - as though she deserves to be there, and deserves your respect and your time.
Humility is a key part of this. Remembering that you don't know everything, and that you were once the ignorant newbie yourself, can be very helpful when you're trying to be patient with what you perceive as a stupid question. If you don't remember what that's like, then take a week to teach yourself a completely new technology, and spend some time asking for help on their mailing list and IRC channel. It'll come back to you real fast.
So, how do we go about improving the situation?
If you read books on how to write fiction, the most common advice is to just start writing. The act of writing begets the act of writing. It greases the wheels, and starts your brain moving in a particular direction. As it builds momentum, the good stories start to flow.
Unfortunately this is not usually the case with technical manuals, where you are trying to describe an existing system, how it works, and how to make it do useful things. Some thought needs to go into how you’re going to structure what you’re going to write.
Most software documentation is written by people who are talking to themselves. Without understanding who you are, in fact, talking to, documentation tends to answer the wrong questions.
The first thing that you need to understand and embrace when you sit down to write documentation is that your audience is not comprised solely of young white wealthy English-speaking men who grew up watching Monty Python.
I specifically mention Monty Python because of the Python documentation. On the whole, it is great documentation. It is thorough, contains numerous examples, and is written in a voice that is very accessible. However, many of the examples are Monty Python jokes.
FIG 1 - Python doc snippet.
Understand that I'm not saying that this is necessarily bad, but I raise it so that you can think about the implications of inside jokes in technical documentation. Inside jokes form a sense of community. ("These are my people. They get me.") But the flip side of that is that they clearly point out to people outside of that community that they don't belong. They raise a barrier to entry for people that have a different life experience. They're probably bright enough to realize that a doc example about a dead parrot is some kind of an inside joke, and that they're not in on it.
More subtly, colloquialisms can have a similar effect. Consider this example from the php docs:
FIG 2: strpos doc from php
For a native English speaker, or to someone who is fairly fluent, this is a great example. "Find the needle in the haystack" communicates immediately, and you know which argument to the function is the needle, and which is the haystack. To a non-native English speaker, they likely have a similar expression in their language, but initially the reference to a haystack in this context may be confusing.
As with inside jokes, colloquialisms give a shortcut to a concept, and establish a sense of belonging, because you get the reference. But to someone outside, this can "other" them.
In determining who your audience is, it can be useful to employ "personas", which are a technique used by professional documentation specialists to figure out who they are talking to.
Based on user surveys, interviews, or otherwise talking to the users of your software, create profiles of the users of your software. Give them a name, a job, and perhaps even a photo, so that when you're writing you can ask yourself, what would Sally need to know in this situation? That can provide a great deal of focus when you're stuck writing.
We'll talk more about what voice to use in a moment.
If you build it, they probably won't come. Whereas 20 years ago, software came with a printed manual that everyone had, these days there's dozens of places to get information about your software. Some of it may be better than others, but the unavoidable fact is that your users are having the conversation somewhere else, and you need to go to them before you can persuade them to come to you.
Go to IRC, to StackOverflow, to third-party howto sites. See what questions are actually being asked, and make sure that your documentation answers those questions. Then engage in the conversation there, where it's happening. Part of this conversation should be pointing them back to the official documentation, where the right answers live, and thus build confidence in the docs, and, possibly, shift the conversation back to your official communication venues - your mailing lists, forums, or wherever.
Anne Gentle says in her book "Conversation and Community", "We may know what they need to know, but only they can tell us what they need to know." And then only way for them to tell us is if we go to where they are and listen to what they're saying.
FIG 3: ThereIFixedIt
For the most part, people are just looking for solutions. It's no longer possible for almost anyone to understand all of the technology they use. Instead, they need to know enough to make something work so that they can move on to the next time. This can lead to solutions that aren't exactly ideal, but get the job done.
Thus, while it's important that we answer questions in such a way that promotes best practice, it's also important to recognize that we have a limited time to work with, because they're more focused on solving a problem than understanding all of the parts.
Anne also says, "End-users do not necessarily care about the source of the information, or whether it was written by a professional; they judge the information solely on its ability to solve their problem."