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

List:       kde-core-devel
Subject:    Re: KDE Doc: We Need Writing Style Guide
From:       Frans Englich <frans.englich () telia ! com>
Date:       2004-08-26 4:05:09
Message-ID: 200408260405.09765.frans.englich () telia ! com
[Download RAW message or body]

On Wednesday 25 August 2004 13:20, Aaron Seigo 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


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

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.

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

These tree issues(letters) overlaps the three areas above(numbers) in terms of 
relevance, and I find it hard to tell where those guidelines should be 
placed(in what document).
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?

How have other DEs solved it?

The GNOME folks, as usual ahead on the usability front, have this extensive 
doc:
http://developer.gnome.org/documents/style-guide/

Apple have a couple of docs on this.. One is called "Apple Publications Style 
Guide" on 200p. (developer.apple.com)


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..) 

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.

Anyway, I had planned to look at this a little bit later, so I haven't studied 
the docs mentioned closely, and I'm probably big time wrong on a lot of 
things. But I think this should be sorted about before we start writing for 
real.


			Frans




["kua5" (text/plain)]

Name: KUA5 Words & Phrases

Description: Lists what words and phrases which should be used instead of others, and \
those which shall be avoided completely.

In order to select good words to be used in documentation and interfaces, and do it \
consistenly this KUA exists to coordinate this. Apple has a similar document, called \
"Apple Publications Style Guide", which covers several hundreds phrases, although it \
is primarily ment for publications. We could copy its phrases right into this \
document, but it would not be of much use, since it is not tailored to the usability \
dilemmas open source/KDE has. This KUA is not as extensible as it needs to be, and \
the cure is that you, the reader and most likely developer, is not passive, but \
actively reflects on the development, and folds back discoveries into this document \
so it can be of use for other developers. Drop a line on mailinglist kde-usability, \
in case you think corrections or additions needs to be done.

The reader perhaps wonders how a long list of phrases should be useful. Should it be \
read and all of it remembered? If texts are designed consciously, the usage of this \
article comes by itself since situations will be encountered where it is unclear what \
words are preferred, and how consistency with the rest of KDE environment is \
achieved. When doubt over what words to use is prevalent, this article is used as a \
dictionary.

This article dictates words, phrases to not use at all, or use instead of others; a \
matter subjective and conventional, dependent on what the targeted user audience is. \
The userbase defined in KUA2 is used as background, resulting in a language tailored \
for regular users. For example, a common word like "link" is preferred instead of the \
exact technical equivalents - URL or URI. However, in seldom cases another userbase \
is targeted, for example a web development program can be expected to have a more \
technical compentent userbase, and another language is more suitable - in the example \
above, using URL or URI can be fruitful since the targeted audience can make sense of \
them(know their meaning).

TODO I find this interesting, found on AskTog:
"Do not use the word 'default' in a program or service. Replace with 'Standard,' 'Use \
Customary Settings,' 'Restore Initial Settings,' or some other more specific terms \
describing what will actually happen. Should we cook something up?

TODO Decide on programs' vs programs's
TODO lets vs let's
TODO Do or Do Not adress the user with "you"?

TODO...

* Preferences/Configuration/Settings

* Use double quotes(") instead of single quotes(') when phrases needs to be isolated \
in texts.

* CD Writing - CD Burning

* Program - Application

Period - dot
When referring to the letter(".")

* Folder - Directory
Folder is metaphorical and less technical.

* Administrator - Root
Root (user), is a technical word and have no metaphorical meaning, as opposed to \
administrator. However, references to the administrator, in the sense "ask your \
administrator to ...", should be avoided since the user usually is the administrator. \
Instead, explain where/how the user can perform the administration. When referring to \
the "root" in the file hierarchy("/") the term TODO toplevel? should be used, for the \
same reasons as above.

* Monitor - Display
When referring to the physical monitor, the "view" the user has, use Monitor instead \
of Screen/Display or any other synonym.

* Polarity
Avoid polarity since it is a scientific word. Use plain English, perhaps "direction" \
is suitable?

* Mapping
Too scientific. Perhaps "order" is suitable?

* Parse
A too scientific - is the information you provide useful at all?

* Restart - Reboot
Avoid technical jargon

* Start computer - Cold/Warm boot
When referring to starting, turning on, the computer.

* Details - Advanced
Use "Details" instead of "Advanced" on expanding dialog windows("Details >>" button) \
or advanced dialogs("Advanced..." button). The content in such areas are usually \
technical, "advanced" and not often used. "Details" explicitly tells it is not \
important which "Advanced" does not - something may well be advanced but still \
important. "Advanced" is descending on the user since it implicitly say the other is \
the easy, obvious and regular. "Details" does not emotionally prevent the user to \
explore, since it is not necessary to know about "Advanced" computers.

* PID
Leave it out. A fraction of the userbase knows what it means, and finds the \
information useful. Print it in standard out, if absolutely necessary.

* When doing contractions use [...], not (...) or just ...

* GID
Leave it out. A fraction of the userbase knows what it means, and finds the \
information useful. Print it in standard out, if absolutely necessary. If it is \
strictly necessary to know the group, show the name instead of the internal ID which \
is ment for implementation use.

* UID
Leave it out. A fraction of the userbase knows what it means, and finds the \
information useful. Print it in standard out, if absolutely necessary. If it is \
strictly necessary to know the user, show the name instead of the internal ID which \
                is ment for implementation use.
* APM - Power Management
* ACPI - Power Management
* URL - link


["kua6" (text/plain)]

Name: KUA6 Designing Texts

Description: Discusses what to consider when designing texts.

Texts are one of the most central ways of communicating with the user and appears on \
virtually all kinds of widgets. Considering texts's central use, it is crucial they \
are designed with care. This article deals with texts used in graphical user \
interfaces(GUIs), labels, dialog boxes and so forth, although it is useful for \
writing code comments and manuals, too. When the term "text" is used, it refers to \
labels, buttons, menus and so forth in the program, not text the user have created. \
Texts used in GUIs is a completely different chapter compared to where texts usually \
are encountered - books, news paper articles, and so forth. All that affects its \
design, context and purpose, differs. Thus, a different thinking must be applied when \
designing for GUIs than when chatting with a friend, for example.

When texts appear, they have as role to inform the user when interaction with the \
program is necessary - answer a question via a message box, or help the program by \
configure it, for example. Texts are not what the user is using the program for, they \
are communication overhead. The perfect program does not contain texts since the user \
does not have to read about the program, only the content is there, a document, for \
example. While such a state is hard to achieve, it should be strived for. Texts \
should be avoided at all if possible - an intelligent program instead of dialog \
boxes. Texts, as in all other engineering, should be kept simple, concise and achieve \
their goal and nothing more - communicate their information. Don't let your ego shine \
through in texts. Don't phrase like the user finds it a pleasure to read the text, a \
widget or message box brings. Remember, you may be interested in the program, but the \
user is not, and sees the message box or label as an interruption in his/her work.

TODO I have read somewhere, research indicates users tend to not read texts(messages \
boxes etc). I can personally confirm this, but we need a reference. Any ideas? It \
would be suitable to mention it in this KUA, anyway. TODO We need guidelines on how \
to quote, use footnotes, etc. etc. TODO Enumerations or lists of paragraphs should \
not end with a period("."), except the last. TODO how to enumeration

The creation of texts can be divided in two parts - the practical and technical, how \
the text's content is presented, and the actual content the text brings. Let's start \
with the former.


A text has a content the user needs to be informed, as efficient and easy as \
possible. The actual interpretation of the text must work, as well as nothing more \
than the message should be delivered. Of course, this sounds easier than it is.

* Don't be in any way emotional, it is usually interpreted as embarassing and an \
intrusion of the user's personal sphere. The message the text delivers is objective \
and does not need the emotional element, which furthermore is energy consuming and \
                focus stealing. When put in practice, it means you should not use:
-) Smilies
-) Capital letters. They are interpreted as screaming and frightening(as in ERROR)
-) Exclamation marks
-) Question marks, unless it is a question the user must answer
-) Do not pull jokes or in any way imply the message is funny
-) Do not use irony. The usage of quotes around words is an indication.

* Be objective, not subjective. The message's content is neutral and is usually a \
short statement. Hence, it should not be valued by you. Avoid adjectives and \
superlatives, search for "very", "bad", "dangerous" and so forth. Doesn't the text \
become dry and "bureaucratic" when being objective? Being objective is not equivalent \
to being bureaucratic. Use as simple, plain, daily English as possible - not cryptic, \
advanced words.

* Do not personify the system by writing "I", acting as a person.

* Don't list alternatives with slashes("/"), because it complicates translation and \
is easily misunderstood. Instead, phrase it so a pleasent reading flow is allowed, \
and your point is clear. For example, instead of writing "developer/user" write \
"developer and user" or "developer or user", depending on purpose. Of course, one can \
wonder where the usage of the word "developer" could make any sense.

* Be explicit. The user should not need to think what the text tries to say, it \
should be obvious. Go straight to the point. If a phrase ends with ".." or "...", \
implying after thought, it is a severe indication the text is implicit(as well as \
emotional).

* Be consistent. Ensure you have internal consistency in your program by always using \
words with the same implications. Also, follow the guidelines in KUA5 to be \
consistent with the KDE environment.

* Be understandable - always use a language as simple as possible. Talk the language \
of the user, achieved by first defining your program's userbase, done for you in KUA2 \
if it's part of KDE(it most likely applies anyway). For example, if a frontend for a \
C++ debugger has a function described as "jump to end of frame stack" it requires far \
more than just C++ knowledge, it requires insight in how software works on the \
hardware and low system level - the developer obviously knows, but the overwhelming \
majority of the users does not. The language you as a developer, with deep technical \
knowledge and an eventual computer science graduation, is comfortable with, is not \
only inunderstandable but frightening for the vast mjority of your userbase.

-) Do not use words only those who read RFCs, computer magazines and so forth know. \
For example, only engineers know what "APM" and "ACPI" is, but everyone can \
understand "Power Management". Similarly, instead of using "URL" or "URI" simply use \
"link" - no one knows what the former means and the exact difference is not of \
interest. However, if it is to be used in a web development program, or any other \
situation where a technical competent audience is targeted, the phrases have a \
different meaning and hence may be suitable. In general avoid short forms, especially \
technical ones.

* Use a structure allowing a comfortable reading flow. If you have phrases separated \
by many conjunctions, such as "but", "which", "and", "or", commas, and so forth, it \
indicates a cumbersome text. Most likely, the text is too long and elaborated, and \
hence the problem lies elsewhere. Do not use paranteses at all.

* Do not make assumptions. You, the developer, have compared to the user a deeper \
knowledge, technically as well as about the subject. This difference must be taken \
into consideration - position yourself as a typical user with respect to the \
userbase, and consider her/his viewpoint. Have as rule to take nothing for granted. \
Be careful when considering writing "obviously", "of course" and similar - why are \
you then writing it? If something was obvious, the text would not be there. It is \
also descending on the user.

* Cut corners. It is not enough a statement has a potential use, it must be widely \
used, and be centrally relevant.

* Do not provide information by altering the font color, since it is a complication \
for color blind users, as well as various monitors has a distorted color spectrum in \
alternating viewing angles. Especially men, 10-20%, are expected to have color \
blindness of some form. If you need to emphasize an element, make it bold or phrase \
it differently. Avoiding color elements also have the advantage of giving a visually \
unified and assembled impression.


The content, the message the text communicates, is usually dependant on the \
situation, whether it is a configuration option or a menu entry, for example. Though, \
some general remarks can be done.


* As stated, talk the language of the user, but also have content which is user \
oriented. For example, if the solution for a certain problem is to recompile the \
kernel, load a module, or other similarly technically advanced, do not ask the user \
to do that, or tell that is the solution. Instead, either do not mention it at all, \
"hide" it, or put in a general way. The vast majority of your program's userbase is \
not like you. Keep your targeting audience in mind.

* Do not mention technical details and implementation issues. The user cannot care \
less. We are not designing for engineers, but regular users. For example, if a \
burning program displays the writing speed with the caption "Estimated Writing Speed" \
- does the user care if the writing speed is estimated or not? While it from a \
logical perspective is a lie to skip "Estimated", does it matter for the user? \
Remember, the user interprets and thinks about every element in a text. Another \
example: Who, except a power user having Hardware/Linux as special interest, can make \
use of the following message? "Cannot find the Sony Programmable Interrupt \
Controller. Make sure the sonypi driver module loads without failure" As developer it \
is easy to drift away from realities and think the user have the same insight in the \
underlying system as oneself. The user does not distinguish between Linux, KDE, and X \
Windows, or what the difference between KParts, KIO Slaves or a regular program is, \
for example. What if you bought a car and the instrument panel used symbols and \
language only car engineers could understand? 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.

* Do not state the excessive and obvious. For example, don't suffix a title \
representing a section in a configuration dialog with "configuration" since it is \
obvious - it is a configure dialog afterall. For example, instead of calling a \
KControl module "IBM Laptop Hardware Configuration", call it "IBM Laptop" since it is \
obvious it's about hardware and configuration. The same reasoning can be applied to \
menu entries. For example, instead of calling an entry "Foot Notes Manager" or \
"Paragraphs Configuration", they should be reduced to the key words, "Foot Notes", \
and "Paragraphs", respectively. The reason is texts in GUIs differs from texts in \
ordinary cases. While "Foot notes Manager" may seem more complete, it does not \
correspond to how it is used, how the user thinks when using a program. Concepts is \
not represented by long phrases like those found in books, but keywords, similar to \
supporting words scribbled down for a speech. Hence, texts representing \
functionality, such as menu entries, may appear ackward when read as a literal text \
but works excellent when used as supposed to be. Naming categories and menu entries \
is complex, and too extensive topic to be covered here.

For every element in the text, question what purpose it have and why the user needs \
to know it - how the information will be used. If it does not have a meaning, remove \
it since it only causes confusion and unnecessary interpretation. It's not enough \
there is a possible usage, it must be widely used, and useful for the majority of \
users. The user should not need to skimm the text for important and relevant \
information - the developer should do it for the user. Sometimes a text can simply be \
redundant. For example, the "IBM Thinkpad" module in "System Administration" shows \
the message "Thinkpad Buttons KMilo Plugin Ready For Configuration" on startup in \
case everything works. What if every program states it works as it's supposed to do? \
The user does, for good reasons, assume things works and hence the text is redundant \
- the information is not in anyway useful[1].

TODO An accessibility perspective. What should be taken into consideration?

At the end, a handful of examples illustrating bad text design. Perhaps you can \
figure out what makes them bad examples? Should they be rephrased? What happens to \
the text if simply the inappropriate words are removed?

* A menu entry called "smbUmount"
* A doxygen code comment phrased "Setting it to 'off's may cause trouble starting the \
                computer. USE WITH CARE ! :)"
*. Configuration options for the mouse titled "Button Mapping" and "Button Polarity"
* A message box reading "Now Listening for Kopete - it would tell you what I'm \
                listening to, if I was listening to something on a supported media \
                player! ;-) "
* A label saying "Could not read /dev/nvram. If you have an IBM Thinkpad load the \
nvram Linux module insmod nvram or create the node mknod /dev/nvram c 10 144 then \
                make the device readable chmod 664 /dev/nvram or writable chmod 666 \
                /dev/nvram."
* A standard out message saying: "ERROR: KDE seems to already be running on this \
                display."
* A checkbox called "Enable the KDE Wallet subsystem"
* A menu entry called "Parse File", in the menu "File"

Footnotes

1.
Sometimes the implementation tricks one's mind. The message was constructed in a \
if-statement; first a couple of error checks were done, and if those were passed(if \
else), the label was given the everything-works message, instead of any of the error \
messages. As the developer it is easy to think - if I tell the user when it does not \
work, I should of course also tell when it do work. When showing that message, the \
implementation is exposed since it implicitly tells it may not work. Instead the \
label should be hidden.



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