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

List:       kde-i18n-doc
Subject:    Re: Criticisim about KDE documentation
From:       Marko Samastur <markos () elite ! org>
Date:       1999-12-13 18:57:57
[Download RAW message or body]

Hi,

Eric Bischoff wrote:
> 
> 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.

As occasional writer for computer magazines, I agree with Al to some
extent. Documentation, that is available on the web (the one you find if
you follow the "documentation" link) is very much out of date. Quick
start and User's guide were written even before 1.0 release.
On top of that, they don't describe nearly enough. They are good enough
only for first steps in KDE, after that you are on your own.
However, I don't think that there's no documentation. You don't get any
less than you do with other computer programs or packages (which in
general is not much). Sadly, you don't get much more either. And what
you do get, is often not very helpful.
 
> 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.

Judging from my experience, which I hope is similar to other users, that
wouldn't resolve much. There are so many different programs on average
linux distribution, that it gets quickly annoying to hunt for
documentation for each one of them. It should be there in the first
place and if it isn't, I (as I *guess* other users) conclude that it
doesn't exist.
Few times, when I went on a fishing trip for documentation anyway, I
came back more or less empty handed.
Also, as most europeans, I can only dream of free internet access (or
anything similar to that). Therefore it's really annoying to see
programs which have only online documentation. It would be great, if you
could update it with a push of the button, but it should be still stored
locally on a disk.
 
> 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.

This, in my opinion, is the most important thing. Programs in KDE
packages shouldn't be considered finished until they are properly
documented. Lack of documentation should be a show stopper bug.
 
> 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

If you come to conclusion, that there's no documentation, than you can
hardly see huge translation effort being done on that non-existent
stuff, right? ;)

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

I agree with points you've made. Personally, I think it would be helpful
if there was an User's guide book for KDE, that would come with KDE 2.0
and would be accessible from KDE Help. Available help in programs should
be improved too. However, I don't think this will happen until bad
documentation (or complete lack of it) can be a show stopper. Otherwise
there will never be enough time to do it (right). It might help, if
documentation had its maintainers too (or does it have already?).
Developer of particular program could be both, but this shouldn't be a
rule.
I don't know how to get good writers. There's certainly lack of them in
Slovenia. Maybe some sort of a deal could be done with publishers that
would get book published under some open content license. Judging by
slovenian experience (with one of Matt Welsh's books), this could work.

As I've mentioned before, documentation should come with KDE packages. I
wouldn't pack it as a separate package (at least not HTML version
available in programs), because this way it might get sacrificed by
distribution vendors. Considering all possible translations, this would
probably bloat the size of packages considerably, but I still think it
should be done. Other formats (postscript...) could be packaged
separately.

In the end, I must say I feel awkward criticizing work that others put
in existing documentation, since I haven't done much. I'd love to help
writing it, but personally don't think my english is good enough and I
doubt I know enough about KDE. I intend to continue my work on
translations, where my amateurism is not so obvious. If there's
something else I could do, but haven't thought of it, I'd be please to
know.

Best regards,

	Marko

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