This is a more or less rambling post based on thoughts which have been sitting around at the back of my mind ever since I started writing my KSquares documentation. During a brief discussion about KHelpCenter on IRC an hour ago it all came spectacularly bursting to the surface so I thought I'd write it all down before anything else bursts.

Program documentation, the stuff you get from "Help -> Foo Handbook..." is an invaluable source of information for users. Despite our best efforts, none of our KDE programs are entirely self explanatory for everyone. I, for example, almost always need to take a look at the docs for most of the games in kdegames when I first play them simply to discover the rules. Also random numbers in the statusbar are another big reason for me going to the documentation simply to find out if a "5" is a good or bad thing.

Unfortunately, despite all the excellent work that's been going on in most of KDE to revitalise and improve for 4.0, there are parts which have been left by the wayside, often because they are kdelibs hackers' side projects. User documentation seems to be one of these sections. Now I don't mean to demean the work of the people who have been working for the last two years to keep the documentation system working as much as it is, but in its current state it's far from release ready.

I could see the dangerous thing happening and I was slightly worried that it was going to be the case that the documentation system was simply going to be given a 'shot of adrenalin' to get it up and running for the KDE 4.0 release. I feel that doing that would be a waste of this perfect chance we have here with the new KDE release series to make a fresh start and change the paradigms we're using for all our favourite desktop environment (that's KDE by the way :D).

Looking at KHC (KHelpCenter) 3 it's always seemed to have a bit of an 'evolved purpose' where new ideas and features have been added to it without any real statement of purpose to the application.

Looking at it now it seems to offer the following:

• KDE Application docs
• Portal for info:/ and/or man:/ KIO slaves
• General KDE help
• Documentation for 3rd party libraries (doxygen, Qt etc.) (Maybe this is a SuSE addition?)
• Searching (via htdig i believe)

Now that's great and it's a good place to go for documentation but I personally think it needs a little bit of a rethink. Both from a user interface presentation point of view and from a 'purpose' point of view.

First, the KDE specific information: Now I'm not going to suggest that we shouldn't have the application manuals available (that would be crazy) so of course, we'd still need those sorted as they currently are (in the same way as they are in the KMenu. It makes sense). But what else would a user want from a 'help centre'? An introduction to KDE, yes. A general pointer to further reading on websites, yes. But the way I see it is that people only go looking for help when they have a problem. And what problems do people have? Well, sit in #kde for a few hours and you'll get an idea. They aren't generally problems that can be solved with just one application, or alternatively they have no idea which application would solve the problem. Maybe they want to change their cursor theme or maybe they want to make the default application for text files to be KWord. Each of these are 'tasks' which require a number of steps to complete but once you've done it once, it sticks in you mind. Or so you would hope anyway :D. It is for this reason that I think we need a sort of 'tutorial' section. A set of walkthroughs for common tasks such as these which the user can easily find via the "Help" icon on their desktop.

That's it.

That's all the user should be presented with when they click the "Help" icon. Application manuals and how to perform certain tasks. They don't care about 'doxygen' or 'iptables' so why give them a list of 20 different items to scan through? I've no problem with KDE having a universal documentation viewer for browsing and searching info or man documentation but that shouldn't be KHC by default.

Hmm, that all came across as a bit 'complainy' but I really do think we need to simplify rather that keep on expanding. Now I know we can't stop distros messing with our software but we've got to do out part too.

Okay, so that was my 'design philosophy' brain burstage, but before I go I had one more thought. When the user does click on "Help -> Foo Handbook" do they really need or want to see the whole of KDE's documentation? I think maybe a lightweight wrapper around help:/ which just opens that application's documentation would be nice. KHC is often slow to start and people who want help often want it NOW.

Well I'm about to have a little meeting with a few people who agree that the documentation for KDE 4.0 needs to be fixed/changed (some more or less radical) so hopefully soon we'll see some results.