From kde-i18n-doc Thu Aug 26 13:42:32 2004 From: Kevin Donnelly Date: Thu, 26 Aug 2004 13:42:32 +0000 To: kde-i18n-doc Subject: Re: KDE Doc: We Need Writing Style Guide Message-Id: <200408261442.32564.kevin () dotmon ! com> X-MARC-Message: https://marc.info/?l=kde-i18n-doc&m=109352701823352 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!