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.