Jeffrey McManus

How To Document Your Open-Source Tool

I've been poring over the documentation of various open-source tools for the past few years and have collected some thoughts on the subject. All these things seem (to me) like they should be no-brainers, but I see these things come up again and again and it's maddening to me. I desperately want to like a project, but then I see there's no documentation and I think to myself "I'll take another look at this in eighteen months, maybe."

For all the technology we have at our disposal, people still like to read words strung together in the form of sentences. They do this to learn about what you're working on. If you don't have the ability or the patience or the skill to string together sentences, make friends with someone who can, and imitate them. (Step one involves reading a lot.) Failing that, try your best to do your own documentation, no matter how much you know your efforts suck, and get the input of someone who can edit well and give you constructive feedback. I've written and co-authored six books and I'm still in awe of some of the editors and other writers who influenced and helped me.

Here are my rules:

First, if your open-source application does not have documentation, or if the documentation is so sparse as to be useless to someone not intimately familiar with the inner workings of your application, your application is not done.

Second, every software product evolves over time. This is why they call it software (as opposed to carved-into-granite-wear). But the documentation, paradoxically, must describe the state of the software at a single moment in time. Do not get wrapped around the axle describing the fifteen-year history of your product, or how it will work when the next dot-point release comes out. Describe how it works today.

Third, the source code is not the documentation. This is the same thing as saying that because you have a stack of DVDs containing the raw output of the human genome project on your desk, you have a good sense of what your next-door neighbor wants for lunch.

Fourth, if you are using an online group authoring tool such as a wiki (etc.) to create your documentation, great. You still need editing. You still need organization. You probably need an index and a table of contents unless your documentation is incredibly brief.

Fifth: Online browsing is not sufficient. You will need a way to let me download your documentation. You need a way to let me commit your documentation to dead trees so I can read it on a bus.

Sixth: However you choose to author it, your documentation should not contain markup, embedded comments by anonymous users, emoticons, or misspellings.

Seventh: Separate yourself from your agenda and focus on what's useful. Feel free not to cover 100% of the functionality of the system in the first five pages of your documentation. Have the courage to say what sucks about your product. This is one reason why the best technical books on commercial software are often written by people outside the company. I can think of a few open-source tools where people who were very close to the project didn't write the best book on it.

Eighth: Make it very easy for users of your documentation to provide feedback, and be gracious when they do so. Do not reject feedback because it doesn't conform to your paradigm in some petty way. (A few years ago I volunteered to write complete documentation for a little tool that shall remain nameless and the owner of the project said "oh, sure," and proceeded to insist that I begin by hacking up a buttload of XML documents that he'd painstakingly been cobbling together, and that there was no possible way that anyone could contribute to the documentation effort in any other way because to do so would invalidate his incredibly complicated build script. Um, no.) Microsoft figured the feedback thing out in a big way in the last few years — every page of the .NET Framework SDK documentation has a contextual link that lets you submit a documentation bug, and if you submit a docs bug, you get a "thank you" from a real live person in email within a few hours. This is important because it lets the bug reporter know they're being listened to, which makes them more invested in the tool, which makes them more likely to contribute bug reports in the future.

I'm sure that five more rules will occur to me as soon as I hit the Save button.

Comments

Thanks for the suggestions. It's great to have someone else saying the same thing.