[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-i18n-doc
Subject:    Criticisim about KDE documentation
From:       Eric Bischoff <ebisch () cybercable ! tm ! fr>
Date:       1999-12-12 19:22:56
[Download RAW message or body]

Hello everyone,

Please have a look at :

	http://www.twcny.rr.com/technofile/texts/kdoc1299.html

A guy named Al Fasoldt has writes a paper criticizing the KDE Documentation,
that has been referenced by Linux Today. I urge everyone to read it.

First, my reactions :

- Everything he says in this paper is right, and should make us meditate.

- Of course, the way that this has been done that is not nice. Al has never
tried to contact us before writing this stuff. I suspect that he didn't even
follow the "documentation" link from the main KDE page before writing his
article. Nor does he invite people to help us, so this is bare criticism.
Nethertheless, his remarks should not be ignored, because they reflect the
reality.

Now the analysis of the problem. I tend to consider the main problems with
documentation to be :

1) The lack of online copy of our work

	Now that we have the new server i18n.kde.org, Stephan told me that we
	could put some HTML and some Postscript online again.

2) The fact that so far our work has not been distributed along with other KDE
packages

	Our big work should be out at next KDE release, according to Stephan.

None of these big problems is mentioned in the article. Neither is an
appreciation about the huge translation work that has been done (it's normal,
the article has been made by an American chap ;-) ). Instead, his words tend to
say "There's no KDE documentation". Maybe he thinks that there is no KDE
documentation. Of course, he did not dig enough to find us, but I am enclined to
think that it happens exactly the same to the average KDE user, and the cause
lays in the 2 points I mentioned above.

Let's try and be positive. What do we have to do ?

a) Write new documentation and improve existing one - the redaction effort
looks unsufficient to me (not in all areas, of course. For example, KDevelop
comes out with a very good documentation.) Maybe there is also an unsufficient
visibility to the developpers, as would Matthias Ettrich say, and this is my
fault. Lack of time.

b) Translate documentation - we are pretty good at that. Nothing to say about
that.

c) Communicate the results to the outer world. These are the points 1) and 2)
above. To me, it looks like the most urgent. I'll ask to Tobias Burnus :

	What about writing a cron script that would regenerate the HTML and the
	Postscript out of the DocBook on the new i18n.kde.org server ? We would add a
	link from www.kde.org/documentation then. This would solve point 1)
	above. Myself, I'll accelerate the transition to Docbook and this would
	accelerate point 2).

d) Do infrastructure and organization work, choose the right standards, improve
the overall quality on a technical point of view, etc. Thomas Diehl, Stephan
Kulow, Tobias Burnus, and many others do a great job. So does the DocBook
team, but maybe I'm the weakest link in the conversion to DocBook
chain. Lack of time, again, but I must say that this will not last :

	I'll be on holliday soon, and I will work on a half time basis on KDE
	doc from January on, thanks to Caldera sponsoring.

e) Share ressources with other structures : The Open Source Writers Group, The
LDP, Gnome (don't cry ! ;-) ), OASIS, etc..., and communicate with the Linux
Distributors and Paper Book Publishers as well. Big projects are planned.

Any remarks and (soft) criticism welcome, of course.
--
Éric Bischoff
KDE documentation coordinator

[prev in list] [next in list] [prev in thread] [next in thread]