Among other things, I'm a software developer. From what I understand that is supposed to make me genetically incapable of writing usage documentation without experiencing great pains in my head and various extremities .. or something along those lines. I wouldn't know, really, because I've generally run screaming from the task. I've just taken the word of my peers as to the horrors that would, in theory, await. Until this past week ...
I've been poking my head into Userbase and picking at the Plasma documentation there along with a handful of other people who have been writing content there. The revelation for me is how enjoyable it is to do this on a wiki. I spent some time thinking about why it's enjoyable, while I find the old "write it in a local file" method less so. Here are my thoughts thus far:
The wiki gives me instant feedback: I can write something and then preview it in its final form instantly. That's nice, but not as nice as seeing other people's content appear as well. Maybe I'm more teamwork driven than others (which is perhaps ironic, given how anti-team work as a student ;) but that really makes a psychological difference for me.
The discussion pages are great as they let us coordinate. Pages can be written before being linked to, allowing a nice editorial process. New pages that don't exist can be linked to from existing pages as well, giving a nice way to find something that needs doing.
The writing style is also less "describe the details of the interface" and more like a how-to book. Individual pages are topical and bite-sized. Pages can be tagged with categories like "widgets" so we can see all the (thus far) documented Plasmoids by going to the relevant category page. Tagging things with "needs improvement" or "under construction" gives us nice summary pages that work nicely as TODO lists.
I can spend five minutes making improvements or half an hour writing new content, and both are valuable additions. This is letting me "size" my contribution to my time availability. Even just re-arranging existing content into better flows is useful and, with the wiki, easy.
If you can't tell already, I'm completely sold now on the idea of using Userbase to do our user documentation, especially that now we can create offline versions of those documents. I'm looking forward to participating in and watching the continual increase in Plasma documentation and meeting new people in the process. I also understand that Anne is going to be hosting some Userbase days on IRC for people to come together and work on content together in the near-ish future, which should be a lot of fun.
Though .. yes .. I'm still a little conflicted: should I really be enjoying writing documentation? Hmm... ;)