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

List:       kde-i18n-doc
Subject:    Re: [kde-doc-english]3.2 freezes
From:       Gérard Delafond <gerard () delafond ! org>
Date:       2003-09-16 12:41:01
[Download RAW message or body]

Le Mardi 16 Septembre 2003 01:31, Lauri Watts a écrit :

>
> For my part, I'm only dealing with user docs, and desperately in need of
> help.
>
One question (I don't think I can help with the docs writing).
How does the doc writer know how the program works (hidden features, supported 
formats, planned features, etc.)? Does the programmer write some minimalist 
help for the doc writer ?

One suggestion : if there not time enough to write docs, one could spare some 
time, writing smaller docs. I think KDE docs are too detailed. ("Click with 
the left button of the mouse on menuitem xxx, submenuitem yyy to open a 
dialog box yyy..."). Just "Use menu xxx/yyy to open settings...".
 
This sort of writing saves time to the writer, the translator and the reader.

Also, the trivial functions could be not documented :
"Clicking on <<File Open>> opens files..." is this sort of explanation useful 
for anybody ? Some more acurate explanation should more useful (why does it 
not work on my computer ? What is a file ? What is opening files ? Which 
sorts of files can be open that way ? How many in the same time ?)

At the opposite, I sometimes read some docs like this :
"Activate xyz". This checkbox activates xyz function.
OK, but what is xyz function ??

I think KDE-usability should be more concerned by the writing of the docs.

Hope these few ideas can help

Gerard, translator.


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