[dot] Jess Hall Talks About KDE's Documentation

[Dot Stories]

URL: http://dot.kde.org/1116000449/

From: Jonathan Riddell <>
Dept: show-us-your-docs
Date: Friday 13/May/2005, @18:07

Jess 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
[http://users.ox.ac.uk/~chri1708/Phil.html] suggested I should write up
some of my advice for the FAQ
[http://docs.kde.org/en/HEAD/kdebase/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
[http://bugs.kde.org/buglist.cgi?product=docs&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED]
to keep a list of docs that are incomplete or missing. Documentation is
written either as Docbook [http://i18n.kde.org/doc/markup/] 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 [http://people.fruitsalad.org/phil/kde/userguide-tng/] 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
[http://i18n.kde.org/doc] as well as developer and API documentation on
developer.kde.org.
 [http://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 [http://kate.kde.org/] 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?
[http://urbanlizard.com/~aseigo/whatsthis_tutorial/], 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 [http://mail.kde.org/mailman/listinfo/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 [http://docs.kde.org/en/HEAD/kdebase/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
[http://people.fruitsalad.org/phil/kde/userguide-tng/] 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? [http://urbanlizard.com/~aseigo/whatsthis_tutorial/]
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
[http://i18n.kde.org/doc/markup/index.html] 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. :)