Writing application manuals is not something I enjoy much. The last time I touched the manual for Parley, was a half-hearted attempt to update the KDE 3 material and mostly I threw out the completely outdated sections. That lead to a very thin manual that didn’t really contain much information. Now I completely agree that having a good manual is good for an application. That is why we started in coordination with Burkhard Lück to check if it would be possible to use the Userbase wiki to write a new manual. Userbase has come a long way, just this weekend there were some updates. Still, not everything is ready, the new translation infrastructure is being tested just now. So I would not encourage anyone to write their application manual on Userbase just yet.
But the other important aspect, next to technical viability is the social one. How was the experience? Mixed I must say. On one hand, working with Docbook in KDE’s SVN-repository is great because you get the benefits of a version control system. That is something I really miss with the wiki. Wikis have some sort of reversioning, but as soon as you have two people accidentally touching the same part, you are in wiki-merge-hell. That is worse than merging in subversion. You get the whole page displayed and a diff that is quite hard to read. So concurrent editing and wikis is not a good idea. The question is how often do you work on the same manual section with more than one person? This probably depends quite a bit on the project and other factors such as the moon phase. Or the current date. Like last week: we had set ourselves Wednesday as deadline since now we’re in documentation freeze and that means we should give our new fancy, fluffy manual out to translators and included in the official KDE repositories. So the night before that date we had three people working on the manual and I got scared to touch stuff because I might conflict with someone else. This required coordination on IRC, not easy… On other days, this was no problem at all, since updates were infrequent and I never got a conflict. The work has started two months ago already. Maybe we should have split it into different pages. But we weren’t sure if our preliminary structure would work out. Having all on one page helped there. The other point is the conversion to Docbook. With that in the back of my mind, I thought for a first conversion attempt, one page will be more convenient.
I disliked writing Docbook by hand, the last time I tried it. I kept messing up XML tags and the thing wouldn’t compile. I don’t know if there is a better editor for that stuff now, if so, it should be communicated (add it in the comments please). No, I don’t like writing XML, funny thing. And even more, we had Sabine on our team, and I must say, that she did a lot, if not the most work. That is totally awesome, since she’s been with KDE Education only for a short time. I would not have liked to make her learn the intricacies of producing good old Docbook, though I’m sure she’d master it. So instead we got active on the wiki and we’ll now see how we get along converting the thing to something that can be shipped with KDE. Right now we have a first conversion that lacks some links and images. We also need to figure out how to best do Docbook specific things on the wiki. I guess some more templates would be helpful there. With the latest update, Userbase got more export capabilities (if you happen to be in the right groups, for example the translators group) and a new translations framework that is somewhat similar to Ubuntu’s Launchpad. Before you run screaming though, you should try it 😉 I think it’s actually not bad and since you have the source (the actual wiki page that you are translating) in front of you, it’s not as easy to make nonsensical translations. Anne Wilson will write more about the update.
Having an offline version of the manual is important. That’s something I learned when visiting Nigeria: don’t take a fast internet connection for granted. A manual that can be shipped on CD and opened at any time for reference is incredibly valuable.
Now our joint efforts created this: the new Parley Manual for KDE SC 4.5. And we wouldn’t have gotten there in the time it took us, if we had used the traditional way. I am proud of the hard work and hours Sabine and Daniel (and I) put into it! Most of this was created in less than a week. Sure it’s not perfect, but compared to the old version it is really awesome. I would want to write it this way again. Assuming we get the infrastructure set up to convert to Docbook from Userbase pages without much manual work, I think this is a nice alternative to the traditional way. It leaves some questions unanswered still. For example what about different versions of the applications? For the next Parley version, how should it be updated, considering that this manual is for the release of 4.5 in two to three months. Users still have KDE 4.3 installed… or even older. So we need to think about that. Plasma already has one possible solution for their faq: the page always points to the latest version, with a hint that older versions are available.
Some things that I learned while working with wikis:
- It’s less painful than I thought after getting used to it a bit.
- Section Editing is a great help. If you don’t have an Edit link for each individual heading of the wiki pages, turn it on in your user settings somewhere.
- In order to add multiple images, I created the target links first [[File:Parley some file name.png]] and then I could simply click the newly created links to upload my images. Not fun, but workable.
So all in all, I liked this approach and I’m curious if we can keep the effort up and really produce a good manual in the end. Many thanks go to Anne and Ingo, our userbase experts. Thanks for the hard work on the wiki!
On a completely unrelated note, I just got a new Parley theme by mail, and I’m more than happy to have Jarle support us with his great artwork. Now we have cuddly bees, fluffy bunnies, businessy grey and science fiction:
Ready for takeoff! You rock!