I use KDE, the most usable Linux desktop environment. I wouldn’t go so far as to say I love KDE, but I couldn’t live without it either.
Except on those certain days, that is. When I want to look up something in a help file. This is one of those days.
Frankly, and no offense, but the help system in KDE is disastrous. I should have known by now — I’ve virtually stopped even considering pressing Shift-F1 a long time ago. Mainly because it annoys me no end.
(Edit: In fact, it’s so long ago that I’d forgotten it’s ctrl-F1. Shift happens, as they say.)
I will pass lightly over the fact that many programs don’t have proper documentation. Disclaimers such as “under construction”, “this part needs to be written. Volunteers?” and the like — I don’t mind them, it’s an honest matter that time is scarcer than ideas.
I will also merely mention that to find things in the “Khelpcenter” can be an ordeal in itself. Loads of categories to search through, some of which are ordered alphabetically. And I’ve never been able to search the help files en bloc. There is an option to build a search index of all the application manuals, but every time I’ve tried it, on several different systems (Ubuntu, Mepis, Archlinux, etc.) and with many different versions of KDE, I always get the error message “htdig failed”. A google search reveals that I’m not the only one, but it’s been unresolved for so long that I’ve stopped considering it.
But even when it’s there, it’s usually less than useful. They must have some kind of help file template at KDE central derived from a statistical analysis of most frequent entries in Windows help files. Pages upon pages of things like “File -> Open… (Ctrl+O): Search the file system to open an existing file.” OK, I suppose it needs to be there, but surely there are more important things to spend time and diskspace on?
This mass of trivialities becomes close to ridiculous when compared to the advice one can get elsewhere. I once had the pleasure of asking a non-trivial question at the mailing list of one of the KDE apps. I was greeted with the traditional RTFM (Read The F.\{3,6} Manual), and a list of eleven pointers to places in the manual where my question was answered. Only it wasn’t. Some of them were references to other, developer oriented KDE applications which could be used to accomplish the task in a roundabout manner, others were of the general, non-informative kind above, and others again were of the kind “write a script to do it”. (The whole answer — and the ensuing discussion — was soaked with sulky consternation that I had suggested a Windows program did this better and easier. Proof of point, if I ever needed one.)
In other words: what’s lacking is the middle ground between trivialities and programmers’ tricks. Here, there is something to learn from vim, the uber-geek editor par excellence. I once tried to make a syntax highlighting scheme for Kate, the advanced KDE editor. Nothing fancy, I just wanted to be able to start a line with “;” and make them appear in red to use them as headers in text files. I managed in the end, but it took me forever and a while. Compare it with vim, where it’s done with a couple of lines of easily understandable code.
That‘s user-friendly: it enables me to do what I want to and assumes I am smart enough to understand it, as long as I’m willing to follow some links in the manual and read some very precise but clear instructions. An average KDE help file doesn’t: it tells me what I already know (that I can open a file with ctrl-O), and some things I can’t really use (that this can be done if I’m a programmer), but I don’t get the steps in between, which is where most “users” will be, after all.
Phew. I just needed to get that off my chest. Feel much better now. Think I’ll go and make a syntax colouring scheme.
Real Programmers don’t read manuals. Reliance on a reference manual is the hallmark of the novice and the coward.
No, seriously. you’re simply right. I like KDE, but I wouldn’t use its help system either.
If you said: ‘Real programmers don’t read help files’ I’d believe you. :-)
I guess a real programmer knows his syntax and doesn’t need a reference manual either most of the time, but I would imagine that even a real programmer would need to look up some of the more arcane options to find or grep, just in case.
Then again, I’m not a real programmer…
I have not had that big problems with it, my biggest concern has been the parts that tells me “under construction” and similar.
I don’t know about Kate, but KWrite has some nice syntax highlighting built in. I use it for all my LaTeX needs, as I get exasperated with emacs (yes, it is brilliant and all powerful, but I like being able to easily cut and paste and mouse around inside a document). Anyway, thinking about checking out Ubuntu.
Just a simple question? Would you bee willing to help writing the documentation? For example for some KDE app that you use and know the most. Currently I guess the problem is that there is a lack of documentation writer. And since it is one of the easiest way someone could contribute to KDE it would be nice if people would try to help. Or maybe you see some other solution on how to improve the documentation or motivate more people to contribute in this area. It’s quite easy to see and talk about the problem but much harder to make something about it. So any idea for improvement would be much appreciated and I’m sure KDE documentation writers would like to hear about it.
Yes, I would, but there are at least three BUTs, one personal and two structural:
1. You say it’s an easy way to contribute to KDE, and compared to writing code, you’re of course right, but it still isn’t easy to write useful and meaningful documentation. It requires not only a thorough knowledge of the application, but also an ability to formulate this knowledge. If on top of that the docs follow some silly, uninformative template like the one I mention in the post, it makes the task even harder.
2. Writing docs for some part of a complex like KDE also frequently requires some knowledge of this larger complex: what are kio-slaves? how do libraries interact? how much of kate is also part of Kile? etc. Again: template stuff like “To open a file, click on the file menu” etc. can be writtten without such knowledge, but again: that’s not what I’m after.
3. The only thing worse than nonexistent documentation is inaccurate or inadequate documentation. Say I use KNiceApp — which has no documentation — on a daily basis. I figure out one thing about it. Now, although that bit of information might be of use to someone else, it would make a strange doc page if that was all there was in it.
4. Then the personal: (a) I’ve moved away from KDE, now using awesome and CLI apps mostly, and (b) I’m already too involved with other documentation projects to have time to embark on yet another one.
Your point is good, though :)