Skip to main content

Ralsina.Me — Roberto Alsina's website

Some more about the docs

An­swer to com­ments on my pre­vi­ous docs item. First of al­l, chill­out peo­ple. This is just the blog of a re­tired guy. It's not ex­act­ly In­foworld, ok?

Sor­ry if I ru­ined your day, that was not my goal. I had an idea. Nowa­days, be­ing a re­tired guy, when I have an idea, I ei­ther code it for my­self or put it in my blog so oth­ers can read it. Some­times it work­s, some­times it does­n't.

It was not my goal to say that the writ­ers or ed­i­tor's job is bad. I meant to say that it can get bet­ter, and I had a small idea that may help there.

Rain­er: hm­m­m... well, I trans­lat­ed all of KDE 1.0 (or maybe ear­lier?) to span­ish on­ce, be­fore there was a trans­la­tions team ;-) but I am sure that does­n't coun­t.

I men­tioned in the ar­ti­cle that there is no need to write doc­book, and that you can send plain text to the docs team. I re­al­ly re­al­ly did, so don't ride me about it.

BTW: the docs don't say where to send that plain text email. For ex­am­ple, the kcalc man­u­al says the doc­u­men­ta­tion is copy­right­ed by Bernd Wuebben and Pamela Roberts (in an ob­fus­cat­ed man­ner, but that's ok).

I am damn sure that if you send Bernd an email with cor­rec­tions for kcal­c's man­u­al, he won't ap­ply them, be­cause he has been out of KDE de­vel­op­ment for 5 years. Pamela Roberts I don't know.

So, who ex­act­ly is one sup­posed to send a 20 line ex­pla­na­tion of the M-but­tons to?

Oh, I get it, you are sup­posed to fig­ure out that doc­ (which is not men­tioned in the man­u­al) has a "Con­tact us" link... which sends you to­doc­u­men­ta­tion/ which then sug­gests you learn doc­book (which is not nec­es­sary) and go to­doc/in­dex-scrip­t.php where you are told to con­tact the app au­thor and kde-­

For a 20-­line write­up? Does that sound rea­son­able?

Maybe the tem­plate used to gen­er­ate the docs could be mod­i­fied to add some­thing in the last page, like "For con­tri­bu­tions or cor­rec­tions to this man­u­al, please send email to".

I mean, if that does­n't ru­in your day.

But hey, I can see the at­ti­tude of Lau­ri is more open, at least. And yeah, Lau­ri, thanks for your job, I'm sor­ry I dropped the app lat­er :-(

Sort­ing through the re­al­ly bad garbage is not all that dif­fi­cult. Would I of­fer to triage? Sure, if it's made con­ve­nien­t. Make it come as clear­ly tagged mail with, say, two hy­per­links in it, one for send­ing to docs team for fur­ther re­view, one for declar­ing it crap, I can do a hun­dred of those a day.

Can­l­laith: I share the feel­ing about wi­ki markup. Re­struc­tured­Text is nice, if you find a wi­ki that sup­ports it.

Lauri Watts / 2006-04-04 01:12:

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", 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 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 :))

Roberto Alsina / 2006-04-04 01:13:

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

Lauri Watts / 2006-04-04 01:14:

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

Roberto Alsina / 2006-04-04 01:16:

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.

Rainer Endres / 2006-04-04 01:16:

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

Contents © 2000-2024 Roberto Alsina