Rose Among The Thorns

Writing documentation from a dungeon with two machines and a stuffed fish for company is not as bad as it seems. OK. I lied about the dungeon, but the stuffed fish is real!

Early 2007, I somehow landed in Oslo from South East Asia, on the development floor of Trolltech, surrounded by so many men (a much coveted spot among my female friends mind you) as a Technical Writer for Qt. It's a middle man job, sitting between the developers and the users to ensure that code written is clearly documented so everyone knows how to use Qt.

That's the official job description. The unofficial one is a lot more fun - chasing after developers who make our documentation tool unhappy (it spurts out a long list of errors) and bribing them to fix the errors. Some days I bribe them with rare gems like TimTams or home baked muffins. Other days I just stand outside of their office with a miserable expression. Do I nag them? Never! I just remind them :)

So what does the job entail? When I am not playing Bomberman on the Wii, I spend a significant amount of time documenting classes. The old classes require maintenance and the new ones require a fleshed out Detailed Description with lots of style and consistency checking.

I also write examples on how to use Qt, such as the AddressBook, TextFinder, Previewer, and FormExtractor. Last winter, between brooding over the lack of sunlight and worrying about losing my fingers to the cold, I wrote the Address Book tutorial. Early this year, it was the Qt Quarterly article on QtXmlPatterns. Qt Quarterly is heaps of fun to work on because it gives me an opportunity to drop the formal writing style and write in a more relaxed manner. Also, nothing beats the satisfaction of seeing your name on printed material. Recently, I spent the end of Summer in our uber cool Berlin office helping to document Qt Creator.

Documentation is an iterative process. Hence, all those e-mails to support reporting typos and requesting clarification are very much appreciated from this end because it is very easy to overlook typos and confusing paragraphs. Also, I am subscribed to qt-interest, qt-jambi-interest and qt-creator so if you have comments on our documentation, you can also send them that way.

A quick documentation tip before I sign off: Simplicity

Since Qt is used by developers all over the world, we make a consistent effort to keep the documentation straight-forward and to the point; we also have to keep it simple. A quick example would be:

This signal is emitted when the first (initial) layout of the frame has happened. This is the earliest time something can be shown on the screen.

If we reword it, to improve clarity:

This signal is emitted when the frame is laid out for the first time. This is the first time you will see contents displayed on the frame.

Blog Topics: