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... ;)
Subscribe to:
Post Comments (Atom)
5 comments:
I'm not sure why more documentation isn't written as "how to" it's generally more approachable and useful. I write all my documentation in a howto-ish format. In fact I find specification only documentation useless.
I dislike writing documentation most of the time but when I take a training approach I find it much more enjoyable. Being able to convey the knowledge I have to someone in an easily digestible manner makes it that much more fun.
I mostly prefer editing what other people write. Idea for experiment: wiki-blog - write a blog post, then let other people edit it to fix and beautify your language. I get frustrated when I read your blog and notice a missing word, or when it seems like you struggled and failed to find the right words, or remember the right saying. I mean no insult, but you don't seem to test your blog posts for bugs, and I'd like to fix them.
When I proposed that 5 years ago I got flamed a bit ;-)
http://lateral.netmanagers.com.ar/weblog/posts/P302.html
Finally, I have enough things in place to be able to add screenshots as requested on the Plasma/Kickoff page :-)
I didn't upload the "recently used" screenshot because it's empty for my test user so far. I'll have a play and include it later :-)
Post a Comment