fhwang.net

The virtuous pain of writing your own manual

Today’s release of Lafcadio, 0.9.2, adds a fairly extensive manual to the documentation. There are various tools you can use to write manuals: I wrote mine in Docbook and then used Docbook XSL stylesheets to publish it to HTML. (Thanks to Patrick for pointing out how he did it for Ruby-Web.) But this isn’t really a task where automation can help you much. Writing a manual is a lot of work because writing is a lot of work. This first version took more than a month of my after-work time, which was much longer than I’d expected, and I’m already nervous about how soon it will go out of date as Lafcadio development continues.

Still, I found the process to be worth the time spent. Writing a manual doesn’t just help other people use your software. It also forces you, the writer, to take a bird’s eye view of how your code looks to somebody who’s never used it, which is so easy to lose in the day-to-day when you’re plugging away at a list of granular features and bugfixes. Any strange or arbitrary aspects to the interface become more obvious because the pain you feel in having to explain them probably mirrors the pain of others in understanding them. More than once I found myself thinking “You know, I could just fix this part in the code so that explaining it in the manual wouldn’t take so many damned words.”

Some programmers will tell you that software should ideally communicate its intentions so well that it wouldn’t require documents. This belief is strongest, I suspect, among adherents of Agile methods, and I’d definitely place myself in that camp. But reality often intrudes, and I suspect I’ll never be able to write any non-trivial software that won’t need some explaining.

In the meantime, I’ll probably try to keep updating my docs on a regular basis. I think it’s important to stay close to my users. I wonder what effect it has on the process when you’re in a large technical team, in Microsoft or a major free-software project, where documentation is often delegated to technical writers. Perhaps this arrangement is unavoidable at a certain scale, but that separation also seems like a pity.

One of the many valuable aspects of my tenure at Rhizome was the fact that for more than three years I did the front-line tech-support for a website with more than 1 million pageviews a month. I learned first-hand how easy it is for non-technical users to find web sites difficult or frustrating or even intimidating. And when I rolled out a new change, I could tell within weeks—on the anecdotal level at least—whether it had made people’s lives easier or harder.

After all, who are you writing code for? If you’re writing it for yourself, then no worries. But plenty of us are trying to write it for others, whether those other people are fellow Rubyists or blog advertisers or hedge fund traders. Our profession has a terrible track record at understanding what others need out of the code we create. If you have ways to get closer to those other people, and to understand how to make their lives easier, then those ways are probably time well spent.

blog comments powered by Disqus
Tagged: ruby, software

« Previous post

Next post »


Selected referrals to this page

PRAXIS101: Peter Naur wins ACM Turing Award
First tracked August 7, 2006

… Naur is talking about software descriptions written for software people, specifically, a language description that is read by a compiler writer. The grammar, by itself, is not enough. Francis Hwang recently came to same conclusion; the code by itself is not enough. Documentation is required. It's a common mistaken idea that agile software development approaches are anti-documentation. …

PRAXIS101: Virtuous pain of documentation
First tracked February 14, 2006

… know can't help me, most of the work is mine. | Main
February 14, 2006
Virtuous pain of documentation
Francis Hwang's thoughtful post about the work and value of writing software documentation deserves careful reading. As Francis points out, writing a description of how to use software can go a long way to clarifying and improving the design and implementation. …