Jes Hall Talks About KDE's Documentation

Jes Hall is a new contributor to KDE's documentation team. In the interview below she talks about how she joined the team, how KDE's documentation is made, how you can help them and how they can help KDE's coders. She also reveals the 5 finest examples of documentation in KDE.

Canllaith is a regular helper on #kde

Please tell us about yourself and your role in KDE.

I'm a Unix systems and network administrator and technical writer. I'm a new contributer to KDE and my role is primarily in documentation, although I've made some contributions to Kicker & Kopete.

How did you become involved with the documentation team?

I spent a bit of time hanging out in the #kde IRC channel on Freenode helping users with problems they encountered in their KDE desktop. It seemed after a while a lot of the same questions came up over and over, and Phil Rodrigues suggested I should write up some of my advice for the FAQ. Now I'm the FAQ maintainer, as well as having contributed to other KDE docs.

How many other people are there on the documentation team?

Not enough! There are some developers who do their own documentation, and some people who pop in every now and then with patches - but I think that as far as regular people spreading themselves over KDE documentation in general there are only half a dozen of us.

What functions do the team do to get KDE's documentation into its excellent state?

The documentation team deals with a lot of different technologies working with docs. We use Bugzilla to keep a list of docs that are incomplete or missing. Documentation is written either as Docbook or as plain text and then marked up later. We tend to proofread each others work, and then it's commited into SVN. The KDE build system has a framework in place to process and install docs alongiside applications. We use our mailing list and IRC channel to coordinate efforts.

Documentation is often seen as an example of an area most hackers would find boring, what keeps the documentation team working on it?

We've all felt the frustration of attempting to use a new program and finding it's not easy to use and its documentation is poorly written, or even worse, absent. You can't possibly design an application interface that would be intuitive for all people from all backgrounds, and documentation is what bridges this gap.

I've also always found writing enjoyable, and technical writing gives me an opportunity to write about what I'm interested in, even though it's not 'mainstream'.

What documentation is available within KDE?

KDE has a wide range of user documentation from application handbooks designed to describe an application's function and configuration options in detail to shorter task based documentation. The new userguide is a general overview of KDE - I'd like to see it published as the KDE definitive guide once complete. There are also more task focused documentation in the FAQ and the various KDE Wiki.

There is also a small selection of documentation focused on Docbook and other aspects of writing for KDE up on the KDE i18n site as well as developer and API documentation on developer.kde.org.

What are the tools used to create KDE's documentation?

KDE's documentation is written in a system for writing structured docs in XML called Docbook. Docbook allows you to write once, and then publish in a variety of different formats with no or little modification to your original source files. KDE's documentation is stored in SVN with the rest of its source code, and this is an integral part of working with documentation. Checking files out of SVN, creating patches, applying patches, commiting changes are all part of our regular workflow. The conversion from Docbook source files to the HTML pages that KHelpCenter display is done by meinproc, which is a version of xsltproc customised for KDE's purposes.

The most important tool is a great editor with good docbook support. Kate is my favorite editor for writing Docbook, with the XML plugins availible in kdeaddons.

The applications handbooks contain a wealth of information but are quite monolithic. Is anything being done to make it more accessible?

I believe there is a place for large, detailed monolithic documents for those who do want or need to learn every option about an application in detail. I'd like to see more task focused help that can be retrieved in context though - rather like WhatsThis?, ways of getting to the single help page relevant to an option while you're sitting there at that option, instead of having to open the help center and search for the page.

What changes can we expect to the documentation setup in KDE 4?

I haven't even thought of 3.4 yet! I have one project I'm researching for 3.4 at the moment, which is a multimedia quickstart guide that would double as marketing material. As far as documentation as a whole goes, I have no clue yet. ;)

How does the KDE documentation compare to the competition at Gnome? Are there any moves to standardise documentation formats between KDE and Gnome so only one help reader is needed?

As far as I'm aware, KHelpCenter is already capable of displaying Gnome documentation. I don't actually have any Gnome applications installed to test this, using only KDE when on Unix. I know some collaboration has been discussed between the maintainers of KHelpCenter and Yelp.

How does a developer get started with creating documentation or getting some written?

Write something! We're happy to accept plain text documents and add the relevant markup for you. This goes for any person wanting to create documentation as well as developers. Developers who want to get some documentation created for their application can email us at kde-doc-english and see if anyone on that list has some free time to pick up the project for them.

What can a developer do to improve the documentation in KDE?

Write documentation, even if it's incomplete or even just a rough outline. It's far easier for a technical writer to flesh out a paragraph or two or add some markup to plain text than it is to learn every detail of an application they may not have used before in order to create content. Being available to answer questions about the application is also very helpful. Often what's obvious about an option to someone who can recite the source code backwards may not be so obvious to others and needs a bit of explaining. =)

How can the documentation be improved?

Right now, we're severely understaffed for the job of keeping the documentation up to date. I'd like to see a first stage goal for myself before 3.4 is to help with bringing all the application handbooks up to date and accurate with current KDE versions.

I'm also toying with some other approaches to documentation on the side - improving WhatsThis? help, looking into the technologies required to create interactive presentations detailing specific tasks.

What are the 5 best examples of documentation in KDE?

The FAQ is a collection of questions that are regularly asked on mailing lists and in IRC channels, and if you have a niggle about something it should be your first port of call. It's actively maintained and new question and answer sets are being added regularly.

The userguide is a book that provides an overview of the entire KDE experience. It's designed to lead you through fundamental desktop concepts like using Kicker and Kwin all the way to KDE for administrators with Kiosk and desktop scripting.

WhatsThis? context sensitive application help is also a great example of documentation. It's right there to be read exactly when you want it, rather than requiring you to read it beforehand or switch to another help application to search for it.

The application handbooks, while monolithic are a great resource to anyone who's ever had to support KDE in the workplace. Not all applications are documented yet, but reading through those that are up to date has helped me answer a wide range of user questions about an application.

The KDE Docbook markup guide is a fantastic reference for anyone interested in KDE documentation, and a great example of well written task based documentation. I have a printed copy of this on my bedside table. :)