How (and why) to write good documentation

RTFM? How to write a manual worth reading

Posted 14 May 2015 by 

Rich Bowen (Red Hat)
up
89 readers like this
No swimming sign with alligator biting it
Image credits : 

State Library and Archives of Florida, modified by Rikki Endsley

Definition: RTFM (Read The F'ing Manual). Occasionally it is ironically rendered as Read The Fine Manual, a phrase uttered at people who have asked a question that we, the enlightened, feel is beneath our dignity to answer, but not beneath our dignity to use as an opportunity to squish a newbie's ego.

Have you noticed that the more frequently a particular open source community tells you to RTFM, the worse the FM is likely to be? I've been contemplating this for years, and have concluded that this is because patience and empathy are the basis of good documentation, much as they are the basis for being a decent person.

First, some disclaimers.

Although I've been doing open source documentation for almost 20 years, I have no actual training. There are some people that do, and there are some amazing books out there that you should read if you care about this stuff.

First, I'd recommend Conversation and Community, by Anne Gentle. And if you're looking for a conference about this stuff, there are two that I'd suggest: Write The Docs and OpenHelp.

The title of this essay comes from Kathy Sierra, who in a presentation years ago had a slide that said, "If you want them to RTFM, make a better FM." But how do we go about doing that?

There's common wisdom in the open source world: Everybody knows that the documentation is awful, that nobody wants to write it, and that this is just the way things are. But the truth is that there are lots of people who want to write the docs. We just make it too hard for them to participate. So they write articles on Stack Overflow, on their blogs, and on third-party forums. Although this can be good, it's also a great way for worst-practice solutions to bloom and gain momentum. Embracing these people and making them part of the official documentation effort for your project has many advantages.

Unlike writing fiction, where the prevailing advice is just start writing, when it comes to technical writing, you need to plan a bit. Before you start, there are several questions you should ask.

Who?

The first of these is who?. Who are you writing to? Some professional tech writers create personas so that when they are writing, they can think to themselves, "What would Monica need to know in this situation?" or "What kind of problem is Marcus likely to have around this topic?" and then write accordingly.

At this point in the process, remembering that not all of your audience consists of young, white, English-speaking men who grew up watching Monty Python is critical.

Exhibit A: Python documentation

Python documentation is riddled with Monty Python references:

Screenshot of Python documentation with Monty Python skit references

Now, don't mistake me: Python documentation, is, for the most part, awesome. But there's one complaint I have with it—the inside jokes. The Monty Python humor runs through all of the documentation, and this is a double-edged sword. Inside jokes form a sense of community, because you get the joke, and so you're on the inside. Except when you're not. In which case, inside jokes point out starkly that you're not on the inside. Tread carefully here. Consider including a reference guide that explains the jokes, and, in the case of dead parrots, points to a YouTube video:

The same goes for colloquialisms.

Exhibit B: PHP documentation

In this example from the PHP docs, the English saying, finding a needle in a haystack, is referenced in an effort to make the example more understandable. If you are a native English speaker, the example is great because it makes obvious which argument is which. For readers who are not native English speakers, however, the example points out that they are not the target audience, which can have a chilling effect on bringing new people into your community.

Where?

The next question to ask is where?. Yes, you need to have documentation on your project website, but where else is the conversation already happening? Except in rare cases, other sites, such as StackOverflow, are the de facto documentation for your project. And if you care about actually helping your users, you need to go where they are. If they're asking questions on Twitter, Facebook, or AOL, you need to go there, answer their questions there, and give them pointers back to the official documentation so that they know where to look next time.

You can't control where people are having their conversations, and attempts to do so will be seen as being out of touch with your audience. (While I'm on the topic, they're not your audience, anyway.)

Once, when I worked for a former employer, we discovered that our audience was having their conversations on Facebook, rather than on our website. Those in power decided that we had to stop this, and we put up our own internal social site. And then we told everyone that they had to use it—instead of Facebook—when discussing our organization. I suspect you can guess how well that worked out for us.

But you're doing the same thing when you ignore the audience on StackOverflow, Twitter, and various third-party websites, because they're not in the right place.

What?

On to the mechanics. What should you be writing?

Scope

The first thing you must decide (and, yes, you need to decide this, because there's not necessarily one right answer) is what your document scope is. That is: What topics are you willing to cover? The implication, of course, is that everything else is out of scope, and should be pushed to someone else's documentation.

For example, on the Apache Web Server documentation, we have a document called Getting Started, which covers what you need to know before you get started. The goal of the document is to draw a line saying what is outside of the scope of the documentation, while also pointing people to resources that do in fact cover those things in great depth. Thus, the HTTP specification, the inner workings of DNS, and content matters (such as HTML and CSS) are firmly outside of the scope of the documentation, but everyone using the Apache Web Server needs to know these things.

Types of docs

Once you've determined the scope, and who you're writing to, there are several different kinds of documents that you can write for them. Anne Gentle categorizes them like this:

Start here

Like the Getting Started document I mentioned previously, this is the place where you tell users what they need to know before they even get started.

Reference guide

The reference guide is comprehensive and usually pretty dry. This is where terms are defined, functions' input and output are explained, and examples are given. The tone is factual and to the point. There's not much discussion, or conversation. The voice is usually impersonal.

Tutorials

Tutorials hold your hand and lead you down the path. They show you each step, and occasionally sit down on a bench by the path to explain the rationale for a particular step. They are very conversational, sometimes even chatty. The voice is personal; you are speaking to a particular person, defined in the earlier persona phase.

Learning/understanding

Often linked to from the tutorials, the learning/understanding documents dig deeper. They investigate the why and the how of a particular thing. Why was a certain decision made? How was it implemented in the code? What does the future look like for this thing? How can you help create that future? These documents are sometimes better done as blog posts than as part of the formal documentation, as they can be a serious distraction to people that are just trying to solve a problem.

Cookbook/recipe

There's a reason that the Cookbooks are often the best selling part of the O'Reilly technical book catalog. People want solutions, and they want them now. The recipe, or cookbook section of your document, should provide cut-and-paste best-practice solutions to common problems. They should be accompanied by an explanation, but you should understand that most of the cookbook users will cut and paste the solution, and that'll be the end of it for them.

A large part of your audience only cares about solving their immediate problem, because that's all they're getting paid to do, and you need to understand that this is a perfectly legitimate need. When you assemble your new Ikea desk, you don't care why a particular screw size was selected, you just want the instructions, and you expect them to work.

So it's critical that examples have been tested. No matter how trivial an example is, you must test it and make sure it does the expected thing. Many frustrating hours have been spent trying to figure out why an example in the docs doesn't work, when a few minutes of testing would have revealed that a colon should have been a semicolon.

Recipes should also promote the best practice, not merely the simplest or fastest solution. And never tell them how not to do it, because they'll just cut and paste that, and then be in a worse fix than when they started.

One of my favorite websites is There, I Fixed It, which showcases the ingenuity of people who solve problems without giving much thought to the possible ramifications of their solution—they just want to solve the problem.

Error messages

Yes, error messages are documentation, too. Helpful error messages that actually point to the solution save countless hours of hunting and frustration.

Consider these two error messages:

`ERROR. FORBIDDEN`

and

`Access forbidden by file permissions. (ERRNO 03425)`

The first is alarming, but unhelpful, and will require a great deal of poking around to figure out why it was forbidden. The second tells you that it has to do with file permissions, and has the added benefit of an error number that you can Google for the many articles that detail how to fix the problem.

Philosophy

This entire line of thought came out of years of enduring technical support channels—IRC, email, formal documentation, Usenet, and much more. We, those who hold the answers, seem to want to make it hard for the new person. After all, we walked uphill in the snow to school, and back, with bare feet, remember? We figure out how to make things work by reading the code and experimenting. Why should we make it any easier for these kids? They should be forced to earn it, same as we did, right?

The technology world is getting more complicated every day. The list of things that you're expected to know grows all the time, and nobody can be an expert in everything. Expecting that everyone do all of their homework and ask smart questions is not merely unreasonable, it's becoming impossible.

Compassionate tech support—and better documentation—is the only way for people to use your software effectively. And, if they can't get their answers in a reasonable amount of time, they'll use a different solution that has a better paved on-ramp.

In the first edition of his Programming Perl book, Larry Wall, creator of the Perl programming language and father of that community, joked about the three virtues of a programmer: laziness, impatience, and hubris:

The explanation of this joke is well worth reading, but keep in mind that these are the virtues of a programmer, in their role as a programmer, relating to a computer. In a 1999 book, Open Sources: Voices from the Open Source Revolution, Larry explained that as a person, relating to other people, the three virtues we should aspire to are: diligence, patience, and humility.

When we're helping people with technical problems, impatience is perceived as arrogance. "My time is more important than your problem." Hubris is perceived as belittling. And laziness? Well, that's just laziness.

Being patient and kind, helping people move at their own pace (even when it feels slow), is perceived as respect. Welcoming people at whatever level they are, and patiently helping them move up to the next level, is how you build your community.

Don't make people feel stupid: This must be a core goal.

Even if everyone else in the world is a jerk, you don't have to be.

Doc
Dish

This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us at open@opensource.com.

24 Comments

dboth

Great article, Rich. You nailed it!

I have been in the business for many years and documentation ranges from non-existent to horrible, to incorrect and - very occasionally - to really good. I have written a good deal of documentation myself and have tried to learn as I go. I do not recall ever having seen a class in how to do documentation.

Some of the things you mention were swirling all around even me as I read your article. One list I belong to had someone ranting that another person trying to comprehend some documentation, "learn English," while another list has a continuing discussion about missing documentation for an application I use.

Many web sites that are supposed to contain the documentation for software are so incomplete as to be useless. A lot of times they are requesting help with the documentation, but most people don't care enough and would rather complain than contribute.

Vote up!
7
Vote down!
0
mike pope

>"I do not recall ever having seen a class in how to do documentation."

https://www.google.com/?gws_rd=ssl#q=technical+writing+class

Vote up!
0
Vote down!
0
Hadzijo

I believe the classes had the title of "Technical Writing" :-)

Vote up!
0
Vote down!
0
FredInIT

Great article and right on target!

As part of my CS course work at university include a course in Technical Writing. This course was beyond the normal required Eng101 - Basic Composition. Great course from a great instructor. As a part of the course we had to describe a process, describe an object - specifically a tool and how to use it. Also, had to write to various audiences (neophyte, basic, advanced, guru, etc.).

Something such as this should be required for anyone in any technical field - engineering, computers, etc. Not only did it provide me the foundation to explain things to end users (think- customers) - but also, and equally importantly, to corporate leadership. The folks that decide if you get to keep your position.

I tell my kids - the most important skill you can ever learn is that of effective communication. Above and beyond any technical (professional) capabilities you may gain. If you cannot effectively communicate your thought, idea, or concept to someone else then how far do you think you are going to be able to go with advancing your position?

Vote up!
2
Vote down!
0
The Old Fellow

When I was Technical Director of an IT company in the 1990s, I used to say that a Program without proper documentation didn't exist. I still think that is so. This was a timely and excellent article. Please send a copy to the writers of systemd.

Vote up!
1
Vote down!
0
Russell Dickenson

Rich - An excellent article!

I am currently a technical writer but previously a sysadmin and so can appreciate the value of good documentation. Although it seems odd to some, there are people who *love* to create documentation.

If your open source project lacks good documentation, perhaps put out a call for help. It may not always be answered but it doesn't hurt to ask. For a budding technical writer, having a portfolio of work publicly accessible in version control repositories can be a great way to demonstrate their work and ability.

Vote up!
1
Vote down!
0
conib

I'm very new to open source, after having spent many years in industry as an embedded systems software/firmware engineer. Over the past couple of days I've been engaged in email conversations with some of my industry colleagues on this topic, so this is a very timely article for me.

How does documentation get generated in hardware-centric high tech? Well yes, there are tech writers who are tasked with writing end-user documentation, and there are project managers, architects, and engineers who are tasked with working with the tech writers to help make sure that the end-user doc is complete and accurate.

But also, as a central part of their job description, project managers, architects, and engineers must generate various types of documentation as part of the design and implementation process. Those docs are the first things turned over to tech writers for use in generating end-user documentation. They also serve to bring the tech writer into the design, implementation, and test process in a very substantive way.

What can be applied to open source? What's the first step? Where's the carrot?

What would motivate an open source project manager to generate a requirements spec, an open source architect to generate design doc, and an open source engineer to generate implementation doc?

1) You’d get higher-quality talent contributing to your project, if you made it easier (faster) for them to get up to speed.
2) You'd have something to hand to a tech writer to get them online sooner.
3) You'd likely end up with a better product, period, if you spent some time documenting stuff like requirements, design, and implementation.

Vote up!
1
Vote down!
0
Ed Hurst

Love it. Say it again and often. I'm a customer service kind of guy who loves people and happens to like Open Source, but generally not the people who run the Open Source projects. So I write free books just trying to get outsiders in the door, all the way warning them it's not a nice place but you can sure get a lot of work done. I'm also an experienced public speaker, and maybe someday I'll get a chance to teach Linux to newbies. Until then, I could wish for a buffer zone of folks who aren't so cranky.

Vote up!
1
Vote down!
0
Somewhat Reticent

Read The Full Manual - not the thin little User's Manual. The Full Manual has it all.
Before hyperlinks, we used footnote references.
For auto mechanics, Read The Service Manual, not the Operator's Manual or the Owner's Manual.

Vote up!
1
Vote down!
0
UX-admin

All of this, for what?

Writing documentation is not rocket science, you are not designing the fuel nor the engine, nor do you need to perform physics calculations!

Write the damn documentation so that it is step-by-step: the documentation need only be written so that it is guaranteed that following the steps gets one from state A to state B, and explain what the steps do. "Hold the user's hand"; it really is that simple.

Examples, examples, examples. Describe the program as a reference, but put a ton of examples, even if it seems silly: show the examples such that a clear pattern can emerge when the reader consumes this information. UNIX (especially Solaris) manual pages are a great example of this: they contain detailed reference on every program that is on the system, but every manual page also includes examples, and several of them, so that a pattern can be spotted, and it is written such that it reinforces and rounds up the rest of the manual.

In comparison, manual pages in GNU/Linux operating systems are very poorly written, and examples there are an exception, not a rule, so much so that everyone shuns them, because they are useless for setting things up, and useless for comprehending the subject.

What is good documentation? The AWK and the C programming language books are great examples on how to write general documentation on a specific subject, systematically. If you neeed examples, look no further. docs.sun.com (now docs.oracle.com), or techpubs.sgi.com (the IRIX parts) also also good examples of systematically written documentation.

Again, writing good documentation is not rocket science, and it does not require such extensive philosophy as in the above essay: when in doubt, write it step by step. End of the story!

Vote up!
1
Vote down!
0
Rikki Endsley

You are correct - documentation is not rocket science. Documentation takes a completely different skill set. In fact, I suspect that few rocket scientists are the right people to document rocket science. If it were so easy to write good documentation, all open source projects would have it.

Vote up!
1
Vote down!
0
Somewhat Reticent

It certainly takes a different gestalt - attitude included - but the discipline has its reward.
Teaching something to someone who doesn't find it intuitive brings additional mental circuits into play, and enhances the original skill-set. However, some very bright (in one area) people are not blessed with all the additional aptitudes involved, and may require outright remedial training others grow through at an earlier age.

Vote up!
0
Vote down!
0
UX-admin

It is easy, difficulty is not the problem, the problem are lazy people who would rather write code than write documentation!

Those people have yet another problem, namely that they do not realize that their program is next to useless if in order to use it, one must first reverse engineer it.

Put in another way, their software is only as good as their documentation.

Vote up!
0
Vote down!
0
UX-admin

"I suspect that few rocket scientists are the right people to document rocket science. If it were so easy to write good documentation"

By the way, that is an assertion with prejudice.

One can tell a good engineer from a bad engineer by the quality (or lack of) documentation.

A good engineer will write concise, easy to read, easy to understand documentation. A bad engineer will write poor or no documentation. After all, that is one of the biggest things which make such a person a bad engineer, because their work is shoddy if one must reverse engineer it in order to use it.

Vote up!
0
Vote down!
0
Toad

Having written beginner-friendly step-by-step tutorials there were still people who complained about the documentation because I dared target the writing style and presentation format to the very type of persons complaining. Why do you focus on the command-line instead of telling people to click on button 'XYZ'? Um... the point-and-click way is mentioned and demonstrated later in the document after the steps to install the applications. Alas, there is no satisfying people; writing documentation is time-consuming to do it well yet is a thankless undertaking.

Vote up!
0
Vote down!
0
pilhuhn

I think part of the deviation to sites like StackOverflow is that those make the contributor stand out: they get listed with their name (as it appears automatically below their post), they receive points and status upgrades on successful contributions.
And probably most important: they can just start writing (after registration) without any additional permissions - the (copy) editing is done afterwards by the community and the moderators.
The same applies for blog posts (except for the points).

Vote up!
2
Vote down!
0
Rikki Endsley

Heiko,
You make good points:
1. contributing documentation should be easy
2. copy editing/polishing should be done by other contributors/editors
3. contributors should get acknowledgement for documentation, and their contributions should be appreciated by the community because they are hugely helpful for projects

Vote up!
1
Vote down!
0
tomawesome

Good article. The best line: "Don't make people feel stupid: This must be a core goal." I would like to point that concept out every time I see a readme that says something like:
"Fizbuzz is drop-dead simple to use. In less than 5 minutes I literally made a fully operational RESTful CRUD FPS: Just download from github and load the repo into your persistent post compliant proxy shim class. No code and it works with any tool! What could be simpler?"

Vote up!
0
Vote down!
0
Bravert

Thanks for writing this! I am a budding technical writer myself and have been eager to get experience with software and development-related documentation but have been stymied on how to make inroads. Open source projects were recently suggested to me but as a relatively non-technical (compared to a programmer, anyways) person I was unsure if I could participate by "just" offering documentation. This essay has definitely given me some great pointers, particularly about the mentality needed, and i'm keen to hear advice from anyone else willing to give it.

Vote up!
0
Vote down!
0
Toad

If you can write clearly, concisely, and coherently, please contribute to documentation for an open source or free/libre software project. You could even begin by writing useful man(ual) pages for the numerous command-line applications; make them easy to translate into languages other than English to further encourage other aspiring technical writers to contribute. Alternatively, locate the Wiki for a software project and revise it so it reflects not only the current state of the software but how to implement and use the software. Too many of these project wikis are out of date and leave out important information even when up-to-date.

Vote up!
0
Vote down!
0
salvis

`Access forbidden by file permissions. (ERRNO 03425)`

This is NOT a good error message. A programmer who codes this should be fired IMO.

Any error message about files that does not give the full path and file name is hardly any better than `ERROR. FORBIDDEN`

Vote up!
0
Vote down!
0
emezeta

“a phrase uttered at people who have asked a question that we, the enlightened, feel is beneath our dignity to answer, but not beneath our dignity to use as an opportunity to squish a newbie's ego.”

There are more optimistic approaches to read it I guess.

“When I was born, I wasn't yet «enlightened».
You're just like me.
So, You can!
RTFM man!”

May be...

“What you ask is quite simple. The opportunity to learn by yourself is not going to be crushed by my «warm kindness».

Both of us are the same brute animals.
So RTFM man!”

In another vein, is actually the worst of FM, even worse than none? If not, could it be useful as a starting point?

In any case, "the patience and empathy are the basis of good documentation" in which we fully agree.

Thank you for thinking and writing about this topics!

Vote up!
0
Vote down!
0
signal7

RE: English speakers & "finding a needle in a haystack"

This is a great article, but I'm thinking the above example is poor. If the reader can accurately translate the plain meaning of the phrase, then it should be rather easy to understand the problem to which it refers. Growing and harvesting grasses for cattle is not a skill set reserved for only English speaking countries, as far as I know… and I think other countries have needles as well.

The Monty Python example was, on the other hand, perfect.

Vote up!
0
Vote down!
0
Rocher881

Documentation is a must. Not only for documenting, but also for further development. When you look back and read it, you find rooms for improvement. I've seen pretty nasty documentation which you have no idea what the person is trying to convey, but Intel OA&M API for Linux Operating manual gives a good example of exceptions.www.manualbirds.com/manuals/intel-oam-api-for-linux-operating-user-manua...
Assume viewers are amateurs. I think that's rule of thumb.

Vote up!
0
Vote down!
0

Rich works at Red Hat as the Community Liaison for the RDO project, which is a packaging of OpenStack for CentOS/Fedora/RHEL. He's also the Executive Vice President of the Apache Software Foundation, Open Source enthusiast, and Geocacher.