The documentation for KDE4 is woefully out of date. I don't mean the scattered online wikis, forums and mailing lists that a new user might accidentally stumble upon, but the actual documentation that comes with KDE4.

Click on the Help icon (it's hidden in your menu somewhere). Now take a look. There's a "KDE User's Guide", a "Quickstart Guide", and a "Visual Guide to KDE", all of which refer to (and include screenshots from) KDE3. Even the FAQ is out of date. There's no mention of Plasma, Nepomuk, Kickoff, Activities, etc. The application handbooks are in better shape, it's the basic core documentation that concerns me.

It seems that there's a lot of information out there, but it's just not where the user needs it. Googling for online docs is okay, but that doesn't seem like a good primary source of information. If no one cares about documentation anymore, maybe we should just get rid of it all.

The ever present sore point. I wholeheartedly agree! Get rid of the old in its entirety and get a team of authors from somewhere (this forum amongst others) who work to strict guidelines and start it all anew.

Now that the interface has taken such a huge step forward, why not the documentation as well? It was previously centred around how the menu was structured and explained that the menu entry under file - open would open a file (okay, that was nasty, but true...).

Instead it should be structured towards aims and show the steps that need to be taken to achieve it. Steps can either be links or placeholders that are called up from a database so that any one step (like "open this file") can be used by a number of different apps and therefore has to be written once only.

Am I talking gibberish?

I don't think that "no one cares about documentation anymore". It's simply a lack of manpower, as I see it.

toad wrote:Now that the interface has taken such a huge step forward, why not the documentation as well? It was previously centred around how the menu was structured and explained that the menu entry under file - open would open a file (okay, that was nasty, but true...).

Instead it should be structured towards aims and show the steps that need to be taken to achieve it. Steps can either be links or placeholders that are called up from a database so that any one step (like "open this file") can be used by a number of different apps and therefore has to be written once only.

Am I talking gibberish?

Sounds like a nice idea overall. Though that doesn't really fit into the handbooks, that sounds more like a job for the wiki.
Just collect use cases and describe what steps need to be taken for the target.

And the nice thing about a wiki is, it is easy and everyone can contribute
So be sure to checkout http://userbase.kde.org

There used to be a documentation team, and they did a great job. But they all seem to have wandered off. I used to be on that team, and I too have wandered off. But I'm not blaming the team on this, it's a systemic problem. If the docs were only a few releases out of date, it wouldn't bother me, but when KDE 4.2 will ship with some screenshots from KDE 3.5, something is wrong.

The best solution is to simply have a KDE-wide policy to keep the documentation up to date. There shouldn't be any heavy-handed enforcement, but it should be the expected thing to do. Some big projects manage to do this, so it's not impossible. It just needs a change in culture.

Another problem, which in some ways is not a bad thing, is that everything keeps changing so quickly. Documentation that might have been written for 4.0 would already be outdated as 4.2 comes around. Until things stabilize to a greater degree it's going to be tough to write a lot of persistent documentation.

Nate wrote:Another problem, which in some ways is not a bad thing, is that everything keeps changing so quickly.

I would agree if we were talking about alpha or beta releases. But by the time the software hits the user, it should be complete, including the documentation. Surely now that some major distros are making 4.1.x the default, we can declare it ready for public consumption and get the documentation finished.

Also, "everything keeps changing so quickly" is not going to stop. 4.2 is only one month away, and not even the pre-release freeze has stopped all changes. Then you have the desktop and plasma, which seem to be in a continual state of experimentation and brainstorming.

Some programs have up-to-date docs; some do not. Perhaps the issue needs to be addressed on a program by program basis.

neverendingo wrote:Sounds like a nice idea overall. Though that doesn't really fit into the handbooks, that sounds more like a job for the wiki.
Just collect use cases and describe what steps need to be taken for the target.

And the nice thing about a wiki is, it is easy and everyone can contribute
So be sure to checkout http://userbase.kde.org

Thank you for that link.

It is only for those online, however, and not part of the system. I was after something modular, system internal. I reckon this would be a great idea (naturally ) but wouldn't know how to implement it.

Online would be the place for screencasts and the like (a doddle to do these days with KDE4 :shade:)

I agree that our docs are way out of date. I am the KDE Documentation Project team leader/organizer and would love to get as much help as possible. The reason it is out of date is exactly what some have said in this thread, lack of manpower. The one bad thing I have come to realize about documentation, is it gets boring for a lot of people. Documentation is one of the easiest and most gratifying ways to contribute to an open source project.

I am trying to come up with a bulletproof plan that will allow the documentation to flourish again, and if anyone would like to help, you are way more than welcome!

You might also want to check out the KDE Documentation project mailing list -> https://mail.kde.org/mailman/listinfo/kde-doc-english. It is a low traffic list.

Also feel free to hit me up on IRC #kde-docs as nixternal or email me rjohnson AT kde DOT org.