Moving documentation away from Docbook is not the solution and wiki is a bad idea for doing docs. Once you start on that route you will have endless problems with repurposing, translating and multi-channel publishing. There is a reason for XML, we want to go forward and not backward to structured text formats.



No the solution is not wiki. What is needed is a Web-based front-end that enables people to edit XML and save it. The combination of Apache Lenya and Forrest can do this and the Doco project is on its way.



I do like the idea of annotations. I would take it one step futher though. I would enable users to send annotations to docteams as an XML string using web services. By reviewing the annotations authors can learn what is missing and how to improve docs and make changes accordingly.

I absolutely agree ^_^



A wiki-like system integrated in KDE would be a huge step towards people who want to contribute to KDE in a smaller way. Docbook is OK but not the end.

Well, the idea of annotations being sent to the docteam is mentioned, but I think some things are also important, specially being able to get the improved docs independently of the release schedule.



And no, I am not proposing a wiki, but a wiki-like, moderated system.



It could even have a docbook backend for all I care, as long as you don't need to know what docbook is before contributing.

The GNOME camp got a Google SoC project accepted which afaik revolves around offering Wiki-like editing access to existing Docbook documentation, just bad I can't find the blog link of the one doing it atm...

Did you discuss anything of this with the KDE docs team before you go public?



Did you get any facts why the system is like it is?



Have you ever interacted with the docs team as a translator or documentation writer?



Have you any idea what you are talking about organisation and manpower wise?



All I can see with your proposal are even more untranslated docs.



And the "KDE hackers" are not even up to the job of having an official KHelpCenter maintainer, so stop telling me what KDE Hackers do concerning docs.



Please talk to the people you are heavily bashing and get some facts before you tell the world they are not doing their job.



Just for the record, you do not need to know one line of DocBook to write KDE documentation, since the KDE doc team will happily take over the job to mark up the text. You can send plain text files and it is clearly stated in all texts about it.



Would it have been an idea to read them? To get any information beside your own assumptions?



I doubt you want to do the work, since you not even took it upon you, to jump over to #kde-docs to get some facts or to one of the maillists.



This is a really bad start to communicate your idea with our hundreds of documenters and translators.

You basically told trained technical writers and translators that their work is crap and every 12 year old can do it better.



Thank you for the motivation. This was a really "nice" start to the day.

Uhm, Rainer, I think you should relax a bit. All that Roberto did is throw around some interesting ideas in his blog. He's not bashing anyone.



Besides, you'll have to admit, his analysis of the current issues with the docs is quite correct. Even if you disagree with the solution he suggests.

I understand the KDE-Docs team position that "the system is like that for a reason". DocBook makes lots of things possible and should certainly be the backbone of any serious documentation project.



However, usability-wise, the current situation can be improved. We can lower the bar for user-input, and this would help us immensely -- PHP demonstrated that allowing user input is a good idea, because users might be a few steps ahead of the developers on all sort of things. As it is, the help system does not allow even personal annotations, and that's not good enough. Even just a "big button" to send doc corrections straight from KHelpCentre would be extremely useful (yes, we would need a few reviewers...). It's unfortunate that working on documentation is not considered "fashionable" by KDE hackers :(

Frankly, I don't think I want to read documentation written by anyone who cannot jump the bar "type plain text into your email client".



And updates to the docs are available on docs.kde.org within days.



In any case, I'll be happy to push through Roberto's patch to add annotations to khelpcenter, on the following two conditions:

1: Unmoderated annotations are not shared to other users (so they'll have to go through moderation, and be refetched via GHNS or some such)

2: He's going to help triage out the utter stupidity from the useful content (and trust me, there'll be some), before



This whole idea that there are hundreds of people out there just dying to write docs, is complete fallacy. Roberto should know this; I wrote the docs to one of his apps (at the time, a hugely popular one too) after it had been a couple of years in the wild, because nobody else had even started. In any format, not even a text file.

I love the idea of users being able to keep their own annotations on or in docs somehow. About the wiki stuff though...



It is not possible to lower the bar further than plain text. I recently wrote an article that it was suggested I should put on the wiki. I'm fluent in more than one KDE XML dialect, and I couldn't figure out the wiki markup. I couldn't find documentation on it, it was not like any markup language I'd used before and I really found it difficult.



There is nothing, absolutely nothing more simple than writing in plain text, and sending it in an email to our mailing list. The docs problem has nothing to do with the format the docs are in. The problem is people are more interested in writing long blog posts about what docs people should be doing than they are interested in writing documentation.



This would create far more work for the docs team for absolutely no gain. We'd have to read through all these 'patches' and just like with c++ code, many will not be of a quality we want to accept. We need dedicated technical writers and proofreaders, not yet another long flamewar about the technologies you don't actually have to use to be a writer.



:)

André: The reason we've never advertised it in the docs is *nobody ever noticed it wasn't, in fact, already being advertised*



As for point 2, we've had boilerplate in the docs for about 3 years now to point to docs.kde.org (but currently hidden) because there wasn't the infrastructure to support such a thing. Rainers new framework has solved a lot of the issues there, not least providing stable url's, and so it's finally time that the little triggers we already have in the docs can be enabled.



There's still some big issues to be solved before it can be implemented, but GHNS is still new, and solves most of them.



The problems are perhaps non-obvious though (since someone will ask) for instance, on multi-user systems, if we save updated documentation to ~/.kde we also need to make sure it's removed if a newer update is installed (i.e., KDE on the system is updated), we need to be sure to not overflow quotas by keeping 43 copies of the same documentation in each users ~/.kde (some of the docs are pretty big, certainly a whole lot bigger than say, a wallpaper or an amaroK skin), *and* provide a way for admins to update the system copy.



Then there's the issue of translations - what if you're using KDE in german, and there is an update in English (in the development branch, so newer content) and a newer version of the translation (but in the stable branch - newer content than you had before, but not as new as the development branch version.) Which one do you want? Does your choice differ if you only speak German (I expect it would)? What if you speak English very well, but that English update covers features not yet in the software you have, and the German update does? How do we offer the choice? What if the sysadmin has all the languages installed but you only want English updates. The GHNS interface may not currently be flexible to solve this kind of dilemma.



That's not to say there aren't solutions to all these, but we haven't quite got there yet.

I agree with Roberto that de documentation in KDE is uneven. But, I don't think wikifying it will raise the standard. We had a discussion on the French translation mailing list about opening the translation on a Web based interface for the people who find it too complex to learn KBabel. Our conclusion was that it would diminish the quality of our translations, quality which is, let face it, not stellar today.



The solution is a professionnal, English native speaker, technical writer sponsored by a KDE business friend.



Cheers,

Charles