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

List:       kde-doc-english
Subject:    Re: [kde-doc-english]Re: documentation size
From:       Lauri Watts <lauri () kde ! org>
Date:       2001-05-28 15:18:36
[Download RAW message or body]

On Monday 28 May 2001 14:54, Eric Bischoff wrote:
> Le Samedi 26 Mai 2001 23:29, Tamas Szanto a écrit :

I can barely even answer this, and I never got the original, probably because 
it was known or guessed what my reaction would be.

> > khelpcenter_faq - 136 KB
> > kppp - 146 KB
> > knode - 169 KB
> > kword - 256 KB
> > artsbuilder - 267 KB
> >
> > Well, it seems to me that in most cases (for smaller apps) 50 KB is
> > sufficient for the documentation, and I think that some of these files
> > are simply unjustifiably big. I know that the current policy is to keep
> > the technical and end-user part of the documentation together, but
> > "markup" is definitely for developers only (should be removed from
> > here),

Seems I can't win.  We have constant complaints from users that what they 
want to know is not covered in the documentation, and asking for more, on 
other topics.  We are lambasted all over slashdot and dot for not providing 
enough documentation pitched at the beginners.  There are over a hundred 
applications/daemons with no documentation at all (and don't think I don't 
get complaints about that too) but these *will* have documentation eventally, 
and some of them will be large. I have Krayon's manual nearly ready to go 
into CVS right now.   It's 93 kb unedited, and not near complete or 
comprehensive, so get used to the idea.

> > "artsbuilder" contains just too much material, "kppp" and "knode"
> > could be squeezed a bit and even "kword" is a tad longer than
> > necessary. Smaller files would benefit not only the poor translators but
> > even the English-speaking reviewers ;-)

How ironic, I just the other day saw a developer saying on another mailing 
list that he considered only knode and kppp actually *had* comprehensive and 
"professional" documentation.  I disagree to an extent, because I think there 
are a few other apps that are very complete and well documented, but the 
point is, I don't get regular emails agreeing with you and asking that the 
documentation be reduced.

So here it is: I refuse point blank to limit documentation based on file 
size.   

There is only one reviewer, who is keeping up with the load of docs just fine 
(although straining somewhat under the load of email.)   The *huge* majority 
of the documentation you are complaining about doesn't change much, and 
you'll only ever have to translate it once, let alone the fact that the 
translation work is speeded up substantially with the new system.  

In case I wasn't clear enough: I will not edit, shorten, or reduce documents 
based on file size alone.  If there is any editing, shortening or reduction 
done, it will be done on the basis of clarity and information quality, not 
*ever* file size.  

If you think there's too much then don't translate it all.  I won't put up 
with anyone else doing it either without a fight.  I'm not going to deny that 
some of the docs could do with some editing, that's not the point.  The point 
is, that editing will *not* be done with reducing file size as the main (or 
even any) concern.

Now, you supply me with a couple more people to help with the reviewing, who 
speak excellent english and know docbook (or are willing to learn under a 
hard taskmaster) and can deal with copy-editing text.  Then help me explain 
to a dozen or more enthusiastic and voluntary authors why it seems the 
readers digest has just taken to abrdiging their hard work, and further, let 
me know how to pull all of this off without causing much more complaints that 
the documentation keeps changing and causing much more work for the 
translators.  Do all this, and you might see some file sizes come down.  But 
that will be only the result, not the reason.  

What's even more likely, with that kind of Q&A going on, is that we'll 
finally find the time to finish the unfinished documentation, and write even 
more, new documentation.  As the saying goes, be careful what you wish for, 
you might just get it.

-- 
Lauri Watts
KDE Documentation Coordinator

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