Guy Tiphane
Dr. Davaran
EN 202
April 2, 2003

An Exercise in Writing a User’s Manual

Many of our daily tasks do not require a User’s Manual, mostly because we do not need to communicate how we accomplish them to other people. It is also seldom necessary to write down a description of what we do because we have already trained ourselves, and count on the fact that we will not forget. We often forget how we perform the less common tasks, hoping that we will be able to perform them when they present themselves again. I recently transliterated an English text into Japanese characters using the software available on my computer. Although I could not read or write Japanese, I could set up and use the computer to type Japanese characters into a document. Afterwards it occurred to me that I had already forgotten most of the initial steps in telling the computer that I temporarily wanted to use a Japanese keyboard and that if someone asked me how to do it I would not know how to respond. I then realized that it would be a good exercise to write a user’s manual and to see how difficult this kind of writing would be. The difficulties were many: how much information to give to the reader; simplify and standardize the vocabulary and sentence structure; foresee differences between the reader’s own computer and the writer’s; structure the document so it can be used for related tasks, such as using a keyboard for any other language.

There were three tasks that I wanted to describe to a potential user: how to set up the keyboard to input Japanese characters, how to transliterate English using Japanese syllables, and how to enter the syllabic characters in a document. Each task involved a different style: first, a description of the many steps in Windows to set up a new keyboard model (following a path and trying to show where to go); second, a description of the Japanese syllables and how they relate to English; third, a description of how I used the Find and Replace function in Microsoft Word to replace all the syllables I had entered by Japanese characters (showing a task that the user could simplify if needed). Each section could be used independently and applied to similar tasks.

How Difficult Is It To Simplify?

To describe how to install a different keyboard model in Windows, it was necessary to mention every step of the procedure, so the user would always know where to go next. Because different installations of Windows may not look like the one on my computer, it was also better to describe some of what the user should encounter. In the manual, I used some text to say things like “The Control Panel window opens” and I chose to show a picture of one dialog. These checkpoints were necessary because it is very easy in Windows to lose track of a window or a menu: the user could accidentally click outside the window, causing it to disappear. A checkpoint, in the form of a name (e.g. “Control Panel”) or an illustration (e.g. the “Regional and Language Options” dialog) should also help a user of a slightly different Windows installation in which the steps and the names could be similar but not quite the same.

After describing two or three steps, one realizes that the terminology must be simplified and remain consistent. Although it would be more accurate to tell the user to “select” an item, to “click” on the item removes a level of abstraction, and the terminology is simplified (users now click on something on the screen and do not need to know whether they selected an option or issued a command). User testing should be used to refine the instructions and to make the language even more mundane: the writer must write in the user’s language. A good source for this is the language used in the dominant system’s documentation (in this case, Microsoft Windows’ Help), as such testing should have already taken place for the more resource-rich manufacturer. But what if the writer needs to describe a new system or methodology? The writer should talk to users and subject matter experts in order to build the new language in a way that makes sense to most users.

How to Describe a Transliteration?

Representing English phonemes in Japanese Katakana is a formidable task because the two are so different from each other. In this simple user’s manual, I chose to list all the Japanese syllables, giving a hint of their pronunciation, and then to offer some examples highlighting the fact that sometimes more than one transliteration can be used for the same words. It also became clear that it would not be enough to list English words and their equivalent in Japanese syllables, as some syllables would be better used across word boundaries.

We are limited in this case by the written text: in the task of transliterating there is a significant phonetic component that would be better expressed using an audio guide. In the user’s manual I invited the user to revise his/her transliteration by reading it and comparing it again with the English pronunciation, but we are limited by the experience of the user and our inability to provide a native Japanese speaker to read the syllables accurately. In that sense, would the description of the task be more complex than the description of a computer task? Is it appropriate to talk about a user’s manual when in fact we require that the user develop his/her linguistic competence?

The issue of the complexity of the subject matter in developing a “user’s manual” can be encountered in many other fields: that is most likely why “training” becomes a trade, once the task becomes more than a procedure. People develop unusual skills not by being trained, but as a by-product of their education and experience in other fields. This brings me to think that my user’s manual, in whole or in parts, could be useful to someone but is not likely to reach that reader.

Writing for an Audience That Is Not There at the Moment

How can this text, this user’s manual, relate to a reader? It is likely that somewhere on Earth someone using a computer could benefit from something that has been written in this manual. Following the precept that soon everything that has ever been written could fit on the disk of anyone’s personal computer, this simple user’s manual could actually be part of a global set of documents that could be accessible from any other computer. The audience no longer needs to exist at the moment of writing, but the text needs to remain accessible over time. While parts of the text will become outdated (when, for example, Microsoft publishes a new version of Windows), others will remain useful for a longer time. It is therefore a question of how we can store everything that has been written and make it accessible to everyone.