Arnt Gulbrandsen
About meAbout this blog
2012-07-19

Trolltech's documentation process

When I arrived at Trolltech, there wasn't much documentation for Qt. Some good intentions, some outdated Τεχ source, no plan for improvement. Having suffered from that (I was the world's first external Qt user and needed documentation) I set about writing a usable documentation tool and documentation. One of my jobs became Documentation Supremo. I wrote some/much documentation, wrote the tools, kept track of quality and gradually improved the way we produced our documentation.

I did not write all of the documentation, far from it. While I wrote much and looked at the rest, I could not have written all. It was essential that everyone who wrote code, also wrote documentation.

Our documentation process worked (we wrote documentation and it largely satisfied the readers), so in this post I attempt to document what we did and what made our process succeed.

Sufficient tools were critical. When Haavard and Eirik started out using Τεχ, the process did not work. The documentation quickly fell behind the code.

An example. With the Τεχ process, finding omissions in the documentation required cross-referencing a header file and a sheet of printout to see which functions were mentioned in one but not both. Qdoc (the main tool I wrote) produced a list of undocumented functions, and also a list of likely undocumented arguments to each otherwise documented function, and quite a bit more.

It was important to make the tools stay out of the way. Syntax and features were perceptibly harmful. The ideal documentation tool for a programmer in the zone has hardly any features and offers no control over the output. Qdoc used short tags (\a), did not allow inline HTML, and never asked people to perform chores.

Our needs grew. We needed tool improvement. The biggest example of that was when Eirik wrote the Qt Tutorial, a program which started as Hello World and gradually grew to chapter 14, a simple game, with line-by-line explanations along the way. When we had a new need, we were able to solve it sensibly. Many teams which document try to write such things with the tools at hand, and fail. We improved the tools when that made more sense. Eirik and I sat down with his program, and then we wrote the text and meanwhile I hacked our tool so that it satisfied us as authors.

(Perhaps that example wasn't good. The Qt documentation is API documentation. What most teams need is maintainer documentation, ie. something written just for the team, not for a wider audience. Maintainer documentation doesn't need long tutorials. But I want to write code now, not look a better example. Sorry.)

Morale was usually good, in part because of that. Hackers don't like doing things badly. When the trolls felt that writing writing documentation led to a worthwhile result, without chores, they wrote (not always well, but they wrote, and existence trumps everything).

Interest in the result mattered too. We had myself, who would look at everything written and comment soon, and we had an ever-increasing user base who needed the documentation and said so.

I don't know how much that interest mattered to each troll. But I am convinced that if you (the general you) feel that noone will read what you write, then writing it becomes more difficult and skimping on documentation becomes more tempting.

Without basic writing skills there can be no good documentation. We had many good example texts to emulate, and there was also a co-worker who knew how to and told everyone incessantly.

A digression. I am sad that basic writing is not a part of most programmers' education. Writing is so simple. Creative writing is anything but simple, but the kind of functional writing programmers need needs just a few hours of instruction and regular practice. (Blogging is more difficult.)

We reacted to reader problems. When we noticed that there were support FAQs, we improved either the documentation text or the process. If you look at the setBackgroundColor() documentation carefully, you can see two FAQ answers, which we inserted because of support questions that mentioned setBackgroundColor(). At one point, someone removed the paragraph about setBackgroundMode() because it had nothing to do with setBackgroundColor(). The support FAQs then resumed, the paragraph was restored and the FAQs ceased. Not very logical, but documentation is not engineering.

It's perhaps not something I should say, but a lack of management may have helped the documentation process at Trolltech. There wasn't any scrum master around to ask for demos and never talk about documentation.

After I left Trolltech, things changed a bit. Several people arrived to fill my shoes, they did some things better than I and some things not at all. The documentation's home page was orphaned for eight years.

More documentation was gradually written by technical writers, less by programmers. That led to some better explanations, some longer explanations, to lots of words, and here and there to meaningless drivel. Function setX sets property x. See x for more. Except that x was a single sentence of boilerplate, not more. SetFoo sets the foo without mentioning either the nature or details of foo. Written by someone who didn't understand what foo is or what matters about foo.

I don't have anything to say about a successful documentation process involving technical writers. I know it has been done, I just don't know anything about how.