Plasma in KDE's Wikis

The Plasma team tries to care about documentation. We always fall short of our own high expectations, in part because they are high and in part because we don't have a technical writer in the project. What a difference just one technical writer as a Plasma team member would make!

Still, we have quite a bit of documentation around. This includes API docs, examples and Techbase tutorials. I'm quite proud of the comprehensive documentation we have for things like the desktop scripting, Javascript API and Theme contents (thanks to Marco for updating that one today!) as well as the growing number of examples we are adding.

We have, however, been committing two sins: we've been abusing Techbase as a project community wiki and we haven't been writing end user documentation. We're fixing that, but before I go into details I'd like to point you to Dominik's excellent reminder-by-blog regarding the mission of each of KDE's public wikis. To quote the summary from that blog entry of his:

• TechBase: The primary place for high quality technical information about KDE targeted at 3rd party developers, ISVs and system administrators.


• Community: The working area for the KDE community. It provides a place for sharing information within the community and coordinating community teams.


• UserBase: The home for KDE users and enthusiasts. It provides high quality information for end users on how to use KDE applications.

Community.KDE.org

So everything we have had under Projects/Plasma on Techbase really is supposed to be on community.kde.org. We started, and are very nearly complete, that transition. You can see the results on community.kde.org/Plasma. We've used this as an opportunity to freshen up and reorganize some of the content.

If you are involved in a project that has content under techbase.kde.org/Projects, please also consider moving it over sooner rather than later. I did a few pages a day (so that I didn't get bored by it ;), spending no more than 30 minutes or so at a time doing so. Marco also pitched in with the Theme Details, which has now moved to being a tutorial and out of our community coordination wiki space. So it's very doable, you just need to budget a little bit of time. Best part is that it taxes no brain cells, so makes a great end- or beginning-of-day task for when you'd like to do something KDE but can't bring yourself to do any heavier lifting. :)

All Hail KDE User Documentation Writers!

Next up is user documentation. While in Finland for Akademy 2010 I made a personal commitment to Anne Wilson, one of this year's Akademy Award rockstars, to write user documentation on Userbase for Plasma. It's not quite as selfless as that may sound at first. You see, there are those who would like to see Userbase become the new spawning ground for end user documentation.

This is due to the fact that there are, and have almost always been, just a small group of absolute heroes who have worked on KDE documentation through the years. They have done an awesome job with the resources they have to work with. In fact, one of the key players thus far in documenting apps based on the KDE Platform v4, Burkhard Lück, was also recognized with an Akademy Award this year. There is only so much a small group can do, however, and our software moves quickly. In addition, our users are more and more web-centric when it comes to looking for information.

Wouldn't it be great if we had a way for more people to participate easily in adding to KDE user documentation? How about providing our documentation in a more familiar web format as well? Enter Userbase, a mediawiki-driven site that may just be a key part of the answer. It has a passionate and committed project driver behind it as well in the form of Anne.

The goal is to therefore put more and more user documentation on Userbase where it can be groomed and improved into stunning user documentation. There may be some nay-sayers who think that user documentation is a work of art (and I agree to an extent) and requires skill to do well (again, I agree). The issue, however, is that it's too difficult for those with the skills and sense of the art to get involved. That difficulty is in part perceived ("how do I contribute?" is such a common question) and in part real (barriers not low enough). Remember that many people said the same thing regarding art and skill about encyclopedias and maps. Turns out this kind of content creation does work pretty damn well. Hello, Wikipedia. Hello, OpenStreetMap.

Realizing The Dream

For this dream to enter reality, though, several things were needed. Translation is a solved issue now from what I understand (kudos to those who got that going!), but still outstanding was the ability to generate offline versions of the contents of Userbase so that we don't require going online every time you want some documentation about a KDE application. There was the intent and the desire to work on this, and even a good start to it.

So I decided that out of respect for our users and for the work people were putting into Userbase that I should put some of my own skin into the game as well. So I told Anne that if they got the offline creation of the documentation working that I'd document on Userbase how Plasma Activities work from an end user perspective.

Well, guess what Anne and her co-conspirator Ingo Malchow have managed to do? Yep, they've got automatable offline document creation of Userbase content figured out. There's a remaining issue of whether to use an online service that exists outside of KDE for this, or to set up our own installation of the same (Free! :) software on one of our own servers. That's an implementation detail, though. The hard work has been accomplished in my opinion. Which triggers my commitment.

So I will soon be starting to work on Plasma documentation regarding Activities on Userbase in the Desktop area. I also plan on tidying up the organization of the content that is already there as I go. It will take me several weeks, I imagine, to complete this task. I also hope that by throwing some of my energy into it, that it will encourage others to follow suit. Particularly those amongst our users who are reasonable writers; and remember: if you are concerned about your English skills, it's a wiki .. we can help fix errors if/when they appear. We appreciate content added to the point that it wouldn't even cross our minds to think poorly about good content that happens to have a few English mistakes. We also will need the English content translated so that we can offer this much needed documentation to all of our users across this blue marble we live on together.

I'll keep you all updated regarding my progress and what I learn as I go through it. Anne and I also discussed the possibility of doing Documentation Days, similar to how we used to do Techbase Days (which would be nice to start up again as well) and the very successful Bug Days.

(Speaking of which, did you know that Bug Days are starting up again? Yep! Next one is the 1st of August, so be sure to mark it on your calendar and show up for some bugtastic fun. :)