Bloggin’ it up

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

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

Recently I’ve been working on some library classes for the KDE4 Games module. Firstly a high score table system and more recently extending Mauricio Piacentini’s KThemeSelector to use KNewStuff2 and make it usable by any game in the module.

This is the first time I’ve worked on any sort public API so it was interesting to see the way I do it compared to the rest of KDE/Qt.

Now I’ve never actually used Ruby. All I’ve done is read a few articles on it and look at a tutorial or two. I can’t remember anything substantial about the language but the one thing that has stuck in my mind about it is it’s design philosophy that is most often talked about. That is the way that it caters for the majority of uses by default. By that I mean most classes that are ever written will, for 90% of the time, only be used in one specific way. With maybe a few lines of code that are the same every time the class is used. It is only 10% of the time that the class is used in a way that is out of the ordinary. Because of this rule, API should be tailored towards making it really easy for the 90% of people who only want to do basic things.

Now this sounds like very good philosophy to have when writing an API which is providing an easy way to implement a highscore table or a theme loader. Most tasks should be possible in three lines of code and only the unusual tasks (like custom score fields or loading themes from a different directory) should require more. I think I achieved that with KScoreDialog.

Incidentally, hello PlanetKDE.org! I’m Matt Williams (milliams on IRC/SVN). I’ve been actively hacking KDE for about 6 months (though I’ve been helping out with various other bits for a while before that) now and I’m currently working on kdegames and doing a little bit of work on Plasma.

The four exams I had at the beginning of this term didn’t go too badly. Maths I was much easier than I had feared which is just as well since that meant that I had more time to try the Maths II exam. Maths II was just a baaad exam. I mean everyone found it difficult but it was just nasty. Fortunately Geophysics and Physics of Power Generation went spiffingly.

In all round good news all the lectures for this year are now finished so now I’ve about three weeks until my next set of exams start. In even better news, Lab for this year is over which is just as well since the Lab I just finished was an ‘Astronomy’ lab which involved looking through a telescope, through a mirror on the other side of the room, at a light box above my head with a slide with a picture of Saturn in it. It was probably the most tedious and least worthwhile lab ever.

Now it’s simply a case of winning the upcoming exams to remain on the MPhys course.