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

List:       kde-i18n-doc
Subject:    Re: KDE Doc: We Need Writing Style Guide
From:       Kevin Donnelly <kevin () dotmon ! com>
Date:       2004-08-26 13:42:32
Message-ID: 200408261442.32564.kevin () dotmon ! com
[Download RAW message or body]

On Thursday 26 August 2004 5:05 am, Frans Englich wrote:
> We will apparently write tons of docs. In my work, I've discovered a lack
> of standardization in how texts should be designed, and I think that needs
> some clarification.

Well, call me a twit, but what's all this dirigisme that's coming over people?  
First Gerard, now you!

> I started writing on two KDE Usability Articles but stopped since the above
> needed to be resolved first(and I doubt KUA is the right place). They're
> attached as example; they are buggy and incomplete and duplicate other
> docs(in case that shouldn't be clear..)

With the greatest respect, some of this makes no sense at all.  KUA5 suggests 
using restart instead of reboot, which means we now have three words where 
formerly there was one (ie "restart your computer" instead of "reboot", 
because you have to specify what it is you're going to restart, so that the 
user doesn't think it's restarting a program, for instance).  Is prolixity 
now a desirable element in doc-writing?  Likewise for "default" and "restore 
initial settings".

Some points are non-points - "program's" is "of the program", "programs' " is 
"of the programs (plural)"; "lets" is an incorrect spelling of "let's" (="let 
us"), except where it's the 3rd pers sg of "let".

I don't want to whinge about KUA6 as well, although I could, but to take just 
one example:
"If a problem is solved by creating device nodes or changing permissions, do 
not ask the user to do that - he/she can't. Instead, show a link-label 
stating for example "Permissions for the device needs to be granted, you can 
do so by clicking here" and let the command be run through kdesu."
??? I'd rather know what I'm supposed to do instead of having it done for me 
and possibly messing up something else.  And if you were previously assuming 
that the user can't change permissions by following a text message, you're 
now assuming that he has root access.  In an office environment this may not 
be the case.

I think it's preferable to write some (any) documentation rather than worry 
excessively about whether a comma or bullet point is in the right place 
compared to where it was in some other documentation.

-- 

Pob hwyl (Best wishes)

Kevin Donnelly

www.kyfieithu.co.uk - Meddalwedd Rhydd yn Gymraeg
www.cymrux.org.uk - Linux Cymraeg ar un CD!
[prev in list] [next in list] [prev in thread] [next in thread]