MAY
13
2005

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. :)

Comments

Great interview, but the interviewer should
have asked her if she was free. Especially
becouse she looks so good!

:-)


By Pieter at Fri, 2005/05/13 - 5:00am

or free as beer ? ;)


By Alex at Fri, 2005/05/13 - 5:00am

Is her sex or looks in anyway relevant?

You guys need ot get more out.


By josel at Fri, 2005/05/13 - 5:00am


By Anonymous at Fri, 2005/05/13 - 5:00am

Hello, I think you mistyped the url.. what you are looking for is http://sex.kde.org , where you can have unlimited amounts of free seKx!

(but only according to the terms of the GPL, of course)

---

Now, just to give this Kute looKing girl some positive feedback, I'm now going to say I have actually been reading the whole interview without drooling or fapping.

I'm very happy to see there are people out there who actually enjoy writing documentation.

Keep up the good work and thanks a lot for this informative interview!


By konqi at Sat, 2005/05/14 - 5:00am

First of all, I want to say thanks to Jes for her important contributions and no less a thanks to Jonathan who has been extremely active since he joined the Dot editors. So thanks a bunch for your valuable contributions, both of you!

As for this particular thread, Scott posted the new HIG here. Worth a read.

I have to say I considered closing this thread when you first started it but was afraid I would have been overreacting unnecessarily. I'm glad I didn't, but you sure made me reach. Thankfully Janet responded with humour (posted on Google no less!).


By Navindra Umanee at Sat, 2005/05/14 - 5:00am

This kind of behavior is part of the reason why there aren't as many women in computers. It's really not appropriate in any case.


By me at Mon, 2005/05/16 - 5:00am

Is there any plans on start using a wiki for parts of the documentation? This would allow more people to help, with less effort. I mean, I'm beggining to contribute with kde-i18n-ptBR project, but getting access to the SVN, installing and learning KBabel is not as easy as accessing a wiki, like wikibooks.org.

It could even be made more syncronized with the development process. I'm a developer and I'm using XP and a Wiki in my development process, so I and the users write the user stories in the wiki, I implement the things, they, with my help, improve the user stories, I finish it detailing and adding snapshots of the application, and, when the application is released, 90% ot the help is concluded.

Sorry for the bad english.


By Ivan Čukić at Fri, 2005/05/13 - 5:00am

As written you can send new documentation in either ASCII or Docbook format, no need to be familiar with version control systems. And it's a riddle to me how you want to use KBabel for writing documentation.


By Anonymous at Fri, 2005/05/13 - 5:00am

I'm using KBabel for traduction of the applications(i18n-ptBR).

I think the use of a wiki could be more dynamic in help constucting, because of the just-in-time atualization.


By Ivan Čukić at Fri, 2005/05/13 - 5:00am

The K-3D team (a GTK project) is using a wiki for most of their docs, but they've also written a script that produces other document formats from that wiki. For something like KDE, more work would be required, but the idea itself might be worth looking into.


By Lee at Sat, 2005/05/14 - 5:00am

For translations KBabel are a much better suited tool than wiki, partly because of the type of data a translation consist of. Translations(of UI)also have to be verified on running code, it's not simple text to text translation.

As for writing and translating documentation the teams accept contributions in pure ASCII form, and that's several levels easier than any wiki I have ever seen. Just write the text and let the documentation and translation teams do the rest, can't get any simpler.

On the other side, I think both the documentation and translations of KDE could make use of some new infrastructure. But aimed at the end users, rather than developers. A way to easily update both documentation and translations, using some implementation of GetHotNewStuff. Giving users the ability to update docs and translations independent of KDE releases.


By Morty at Fri, 2005/05/13 - 5:00am

Just had to say that Jes and Philip are very welcomed contributors on the KDE user mailinglists.

Their knowlegde about applications, settings, location of switches, etc. are quite often way beyond what other regulars on the lists know, including developers like myself.


By Kevin Krammer at Fri, 2005/05/13 - 5:00am

yeah, that's so nice to see new people doing such useful work. The doc team rocks! Lauri, Phil and Jess know a lot and they share this knowledge with all KDE users through IRC and docs.
I hope this article will trigger more doc updates from developers! And QWhatsTHis help!
Thanks canllaigh for this lively interview!


By Anne-Marie Mahfouf at Sat, 2005/05/14 - 5:00am

One tool I'd point people at is XMLMind. It's a pretty decent XML editor that lets you write WYSIWIG docbook. I used it to write the tutorial I submitted for the new user manaual.

http://www.xmlmind.com/xmleditor/
http://xmelegance.org/customising-window-behaviour/html/customising-wind...


By Richard Moore at Sat, 2005/05/14 - 5:00am

run khelpcenter and you can get confused easily, There are simply no ICONS to guide you! seems like khelpcenter imitating windows help center ;)

BTW, she is cute! :)


By fr_dude at Sat, 2005/05/14 - 5:00am

You can of course use the Help -> appname Handbook menu entries, as well as typing help:/appname in konqueror to get to help documents if you find the khelpcenter interface isn't as pleasing to you as it could be. There are many ways of getting to docs to suit a wide range of approaches =)


By canllaith at Sat, 2005/05/14 - 5:00am

What's the significance of your handle?


By AC at Sat, 2005/05/14 - 5:00am

ehe :) i really would like to know too..


By wsjunior at Sat, 2005/05/14 - 5:00am

It's a Welsh word that means (to the best of my limited knowledge) family kindness. The significance is that my ex husband's family is Welsh, and I was at my wits end to find a name that wasn't taken on every flipping site I tried to sign up for ;).


By canllaith at Sun, 2005/05/15 - 5:00am

try to become a REAL developer, you are NOT a developer if you write some stupid doc's ...

*sigh*

I suggest reading c++ for dummies ;)

http://www.amazon.com/gp/product/076450746X/102-6245694-1234545?v=glance...


By TranceDude at Fri, 2006/03/17 - 6:00am

Crawl back under your rock, troll.


By cm at Sat, 2006/03/18 - 6:00am

go use windows slut !


By trancedude at Sun, 2006/03/19 - 6:00am