[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:       Philip Rodrigues <philip.rodrigues () chch ! ox ! ac ! uk>
Date:       2004-08-26 10:03:50
Message-ID: 200408261103.56610.philip.rodrigues () chch ! ox ! ac ! uk
[Download RAW message or body]


[I'm not subscribed to some of the other lists this message went to, and can't 
immediately see how to use gmane, so if this message is relevant to them, 
please forward, thanks]

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.
> 
> I see three text areas which needs standardization:
> 
> 1. Texts in interfaces; labels, buttons etc.
> 2. Application/KDE documentation
> 3. In-house documents
> 
> I think 2) and 3) can be treated as same, and is covered by:
> http://i18n.kde.org/doc/doc-primer

Agreed. Use of DocBook for 3 helps standardization too.

> These are issues I've found a lack of coordination(regardles of area):
> 
> A. Details on how to write texts for 2) and 3) above. For example, should
> we use endashes or emdashes? Should bullet lists end with a period? (etc.
> etc.) I guess this should go in:
> http://i18n.kde.org/doc/doc-primer

If we come up with guidelines on these issues, then the doc primer would be
a good place to put them. If you wish to discuss them further, you could
try contacting the proofreaders on kde-doc-english, as they have some
guidelines already, and can tell you more about the issues arising from
using proofreading guidelines.

On the other hand,  I have to agree with David Johnson that we have a lot of
trouble recruiting and keeping documentation writers without adding a
greater burden of very specific house style.

> B. A much needed standardization of words and phrases. Badly needed.
> Should power management be referred to as ACPI, APM or Power Management?
> Display/Monitor? Etc. Etc.

If further discussion takes place on this issue, could you please cc
kde-doc-english, since this might tie in with our renovation of the
glossary, going on at the moment.
 
> C. Rules for writing texts for GUIs; Judging from reading kde-cvs we need
> guidelines that says "don't use smilies; don't use caps; don't pull jokes"
> -- basic stuff

This also applies for documentation, so I'll add it at
http://i18n.kde.org/doc/doc-primer/grammar.html
If anyone comes up with more ideas along these lines, please tell us at
kde-doc-english.

> Should we have "text guidelines" in the HIG, And in the KDE Documentation
> Guide(duplication perhaps)? Or have all text related(such as word
> reference) in the latter and reference that from the HIG and so forth?

I am quite happy to have the same content appear in the KDE Documentation
Guide and elsewhere - the more places the content appears, the more likely
that new contributors will find it. If this is done, we can discuss
technical ways to keep multiple guides in sync (entities, etc).

> I also think we should consider copy what the GNOME devs have done right
> off(HIG/Text Style Guide/whatever's suitable) and rewrite sections which
> are GNOME specific or exclude what we don't agree/understand(that's in my
> plans for some things). The GNOME folks do good stuff, and there's no
> reason to reinvent the wheel. We should also keep in mind that we will
> establish many new rules, and it wouldn't hurt if they happended to be
> identical to the GNOME HIG.

Lauri Watts has an early version of a joint KDE/GNOME style guide, which may
be of interest to you. I can't remember the link at the moment, but if
you're interested, I can find it, along with some more details.

Regards,
Philip

[Attachment #3 (application/pgp-signature)]

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