Some more about the docs
Answer to comments on my previous docs item. First of all, chillout people. This is just the blog of a retired guy. It's not exactly Infoworld, ok?
Sorry if I ruined your day, that was not my goal. I had an idea. Nowadays, being a retired guy, when I have an idea, I either code it for myself or put it in my blog so others can read it. Sometimes it works, sometimes it doesn't.
It was not my goal to say that the writers or editor's job is bad. I meant to say that it can get better, and I had a small idea that may help there.
Rainer: hmmm... well, I translated all of KDE 1.0 (or maybe earlier?) to spanish once, before there was a translations team ;-) but I am sure that doesn't count.
I mentioned in the article that there is no need to write docbook, and that you can send plain text to the docs team. I really really did, so don't ride me about it.
BTW: the docs don't say where to send that plain text email. For example, the kcalc manual says the documentation is copyrighted by Bernd Wuebben and Pamela Roberts (in an obfuscated manner, but that's ok).
I am damn sure that if you send Bernd an email with corrections for kcalc's manual, he won't apply them, because he has been out of KDE development for 5 years. Pamela Roberts I don't know.
So, who exactly is one supposed to send a 20 line explanation of the M-buttons to?
Oh, I get it, you are supposed to figure out that docs.kde.org (which is not mentioned in the manual) has a "Contact us" link... which sends you to http://www.kde.org/documentation/ which then suggests you learn docbook (which is not necessary) and go to http://i18n.kde.org/doc/index-script.php where you are told to contact the app author and kde-doc-english@kde.org.
For a 20-line writeup? Does that sound reasonable?
Maybe the template used to generate the docs could be modified to add something in the last page, like "For contributions or corrections to this manual, please send email to xxx@xxx.xxx".
I mean, if that doesn't ruin your day.
But hey, I can see the attitude of Lauri is more open, at least. And yeah, Lauri, thanks for your job, I'm sorry I dropped the app later :-(
Sorting through the really bad garbage is not all that difficult. Would I offer to triage? Sure, if it's made convenient. Make it come as clearly tagged mail with, say, two hyperlinks in it, one for sending to docs team for further review, one for declaring it crap, I can do a hundred of those a day.
Canllaith: I share the feeling about wiki markup. RestructuredText is nice, if you find a wiki that supports it.
See, this is better - now here is a concrete suggestion, that I can implement almost immediately, that honestly, nobody has ever suggested before (even though it now looks blindingly obvious and you'd think someone would have thought of it before.)
On my next run through the docs, I'll add a line in the credits section to say "If you'd like to contribute to this document, please email corrections or additions to kde-doc-english@kde.org", how's that? Which is an open list, you don't need to be subscribed to post to it. I could probably drop it in the footer of every page without too much trouble (but that raises i18n issues, so I'll start with the easy way out for now.)
And, we've already been talking about a similar link added to the docs.kde.org pages. It's doable, now, with the new framework that Rainer has created. As for links in the mail, well, that's possible too, but might be version 2 as well.
It's not that we don't appreciate concrete useful suggestions on things to approve, we do, honest. What we're all very (very) tired of is "Hey, let's make the KDE docs a wiki! Then all the hundreds of people who can't manage an email client can contribute! and it'll probably stop world hunger too!"
Have a read of this (and follow the links, although I'll let you off the Last Starfighter one if you're not as old as me (that doesn't include you Roberto :))
http://people.fruitsalad.org/lauri/krazykiwi/archives/14-Worse-is-easier.html
And just so I look like a nice guy, I sent the M-buttons stuff to kde-doc-english already ( hope it passes muster :-)
I think the main effect of the annotations system I proposed is that it would be moderated. The crap wouldn't show. Unless it's your own crap, or dominatrix-approved crap, of course ;-)
Which is why although my first reaction was clenched teeth and "oh god, here we go again", I realise your idea is actually better than the average (but notice how many of the comments in reply were the usual "let's have a wiki" blather.)
Why did I decide to tell the world about this? well, three months ago, I was writing a little help viewer for some apps I do which can't require KDE.
I noticed a few things.
1. My help viewer opened in .2 seconds instead of 5, because it's not an independent app.
2. I could add annotations quite simply.
3. I was writing a web backend to manage/feed back the annotations, when I decided that for my clients (who are paying for it) that was not useful, so I stopped.
4. I thought hey, maybe something like that would be nice for KDE.
5. I often have ideas, and I just say whatever I want, and no, I don't go through channels before expressing myself. May be I am an inconsiderate guy. Maybe expecting everyone to contact the docs team before speaking about the docs is, let's say, weird? Am I not to write an opinion unless I talk to you first? That's bizarre.
6. What I said about the docs being uneven, unfocused and superficial is something that happens to almost every documentation, with very, very few exceptions ( I almost say no exceptions). They are not absolute criticisms. Some areas are superficial. Some aren't. Some docs are unfocused, some aren't. That's why they are uneven.
Hell, man, I never said anyone did a crappy job, I only said the job was not perfect. Does that surprise anyone???
Rainer, you are pissed. That's fine. Be pissed. I don't know you. You don't know me. What's the big deal? BTW: I don't think you are a bad guy. I just think you are a little.... well, quick to react.
Well, since I am the bad guy anyway, can you please answer why you decided to tell the world you think the KDE docs are uneven, unfocused and superficial without even talking to the people who do the work?
As you can see Lauri et.al. know the problems and welcome help. Why did _you_ not contact them? And don't start about "somebody" contacting the docs team, we all know there are problems in this and working on it. _You_ know pretty well how to get in contact.
The annotations idea is good in itself IMHO, there was no need to tell the documentation writers they are doing a crappy job, to justify it.