Egoless Documentation

Mark Roth, 2006
published in SysAdmin, 2006

The thing that everyone hates, but sooner or later we all have to deal with, is writing documentation. This, however, is not about the art of technical writing - I'm not going to talk about "tell 'em what you're going to tell 'em, tell 'em it, then tell 'em what you told 'em". Instead, this is about what happens after you write your deathless prose, and how to make it something that other people will actually use when you're not around.

Back in the early nineties, there was a short-lived programming fad called "egoless programming". It took me several years to wrap my head around it, and I've seen some of its tenets moving into mainstream development. The core idea was that code should be reviewed by your peers, who would be expected to criticize it, and point out flaws and improvements. The expected results of this were not only better code, but better programmers. I might note that it was called "egoless" because if you couldn't let your dearly beloved code go, and accept and make the recommended changes, your ego got a bruisin'.

As open source became a big thing, we are, in fact, seeing more and more of this happening as an expected and normal course of development, and even have it moving very seriously into the corporate world. In that world, of course, it's more frequently advocated than actually practiced, and "we've always done it that way", or "that's not in scope for this change" will always trump revision.

Some years ago, having internalized egoless programing to a sufficient degree, I applied the same idea to documentation. The way I've implemented it is like this:

Take in the final criticisms for the final rewrite, and you'll find that you have a document that is readable, accurate, and usable. Let me note that by "usable", I mean something that not only explains something, but that the person who needs to know it will actually be willing to read, rather than try to find you to bother.

Going through this process is never "fun" - it's never enjoyable to have others find fault with your work. On the other hand, it's all in the development process, rather than producing a final Work of Art, and then having it chewed up by management. Then, too, you can get out some of that irritation by bothering the folks you've asked to give the criticism to actually get around to it (they'll be putting it off). Even if you do that, the upshot will be that they'll make sure the document gets used because they were part of the writing.

In closing, I will note that at least once I've actually gone to five or six version, first, because I didn't wait for all the responses, and second, because folks would see the document and come back to me with yet more stuff that they had forgotten to mention, was relevant, that no one else knew about, and that I really did have to add. Even then, the document went official at about a real v. 0.4, and the rest were 1.x updates.

I hope this makes the whole process of creating documentation easier. At the very least, it will spread the pain, and as the old saying goes, pain shared is pain halved.