Open Advice/Good Manners Matter

Good Manners Matter

by Rich Bowen

in: Open Advice

This text is available under the CC-BY-SA license. (see also: Open Advice/Info)

Contents 1 Laziness 2 Patience 3 Humility 4 Politeness and Respect 5 I wish... 6 about the author

I started working on the Apache HTTP Server documentation project in September of 2000. At least, that is when I made my first commit to the docs. Prior to that, I had submitted a few patches via email, and someone else had committed them.

Since that time, I have made a little over a thousand changes to the Apache HTTP Server docs, along with just a handful of changes to the server code itself.

People get involved in Free/Open Source Software for a lot of different reasons. Some are trying to make a name for themselves. Most are trying to “scratch an itch”, as the saying goes – trying to get the software to do something that it does not currently do, or create a new piece of software to fill a need that they have.

I got involved in software documentation because I had been roped into helping write a book, and the existing documentation was pretty awful. So, in order to make the book coherent, I had to talk with various people on the project to help make sense of the documentation. In the process of writing the book, I made the documentation better, purely to make my work easier.

Around that same time, Larry Wall, the creator of the Perl programming language, was promoting the idea that the three primary virtues of a programmer were laziness, impatience and hubris. Larry was making very valid points, and Larry has a sense of humor. A significant portion of the programmer community, however, take his words as license to be jerks.

What I have learned over my years in Open Source documentation is that the three primary virtues of a documentation specialist, and, more generally, of customer support, are laziness, patience, and humility. And that the over-arching virtue that ties these all together is respect.

Laziness

We write documentation so that we do not have to answer the same questions every day for the rest of our lives. If the documentation is inadequate, people will have difficulty using the software. While this may be a recipe for a lucrative consulting business, it is also a recipe for a short-lived software project, as people will give up in frustration and move on to something that they do not have to spend hours figuring out.

Thus, laziness is the first virtue of a documentation writer.

When a customer asks a question, we should answer that question thoroughly. Exhaustively, even. We should then record that answer for posterity. We should illuminate it with examples, and, if possible, diagrams and illustrations. We should make sure that the prose is clear, grammatically correct, and eloquent. We should then add this to the documentation in a place that is easy to find, and copiously cross referenced from everywhere that someone might look for it.

The next time someone asks this same question, we can answer them with a pointer to the answer. And questions that they may have after reading what has already been written should be the source of enhancements and annotations to what has already been written.

This is the true laziness. Laziness does not mean merely shirking work. It means doing the work so well that it never has to be done again.

Patience

There is a tendency in the technical documentation world to be impatient and belligerent. The sources of this impatience are numerous. Some people feel that, since they had to work hard to figure this stuff out, you should too. Many of us in the technical world are self-taught, and we have very little patience for people who come after us and want a quick road to success.

I like to refer to this as the “get off my lawn” attitude. It is not very helpful.

If you cannot be patient with the customer, then you should not be involved in customer support. If you find yourself getting angry when someone does not get it, you should perhaps let someone else take the question.

Of course, that is very easy to say, and a lot harder to do. If you find yourself in the position of being an expert on a particular subject, people are inevitably going to come to you with their questions. You are obliged to be patient, but how do you go about achieving this? That comes with humility.

Humility

I had been doing technical support, particularly on mailing lists, for about two years, when I first started attending technical conferences. Those first few years were a lot of fun. Idiots would come onto a mailing list, and ask a stupid question that a thousand other losers had asked before them. If they had taken even two minutes to just look, they would have found all the places the question had been answered before. But they were too lazy and dumb to do that.

Then I attended a conference, and discovered a few things.

First, I discovered that the people asking these questions were people. They were not merely a block of monospaced black text on a white background. They were individuals. They had kids. They had hobbies. They knew so much more than I did about a whole range of things. I met brilliant people for whom the technology was a tool to accomplish something non-technical. They wanted to share their recipes with other chefs. They wanted to help children in west Africa learn how to read. They were passionate about wine, and wanted to learn more. They were, in short, smarter than I am, and my arrogance was the only thing between them and further success.

When I returned from that first conference, I saw the users mailing list in an entirely different light. These were no longer idiots asking stupid questions. These were people who needed just a little bit of my help so that they could get a task done, but, for the most part, their passions were not technology. Technology was just a tool. So if they did not spend hours reading last year’s mailing list archives, and chose instead to ask the question afresh, that was understandable.

And, surely, if on any given day it is irritating to have to help them, the polite thing to do is to step back and let someone else handle the question, rather than telling them what an imbecile they are. And, too, to remember all of the times I have had to ask the stupid questions.

Politeness and Respect

In the end, this all comes down to politeness and respect. Although I have talked mainly here about technical support, the documentation is simply a static form of technical support. It answers the questions that you expect people to have, and it provides these answers in a semi-permanent form for reference.

When writing this documentation, you should attempt to strike the balance between assuming that your reader is an idiot, and assuming that they should already know everything. At the one end, you are telling them to make sure their computer is plugged in. At the other end you are using words like “simply” and “just” to make it sound like every task is trivial, leaving the reader feeling that they are probably not quite up to the task.

This involves having a great deal of respect and empathy for your reader, and endeavoring to remember what it was like to be in the beginner and intermediate stages of learning a new software package. Examples of bad documentation are so prevalent, however, that this should not be a terribly difficult memory to rekindle. Chances are that you have felt that way within the last week.

I wish...

I wish that when I started working on Open Source documentation I had been less arrogant. I look back at some of the things that I have said on publicly-archived mailing lists, forever enshrined on the Internet, and am ashamed that I could be that rude.

The greatest human virtue is politeness. All other virtues flow from it. If you cannot be polite, then all of the things that you accomplish amount to little.

about the author

Rich Bowen has been working on Free/Open Source Software for about 15 years. Most of this time has been spent on the Apache HTTP Server, but he has also worked on Perl, PHP, and a variety of web applications. He is the author of Apache Cookbook, The Definitive Guide to Apache mod rewrite, and a variety of other books, and makes frequent appearances at various technology conferences.