This is topic PSA: When writing instructions, do NOT use "simply". in forum Books, Films, Food and Culture at Hatrack River Forum.


To visit this topic, use this URL:
http://www.hatrack.com/ubb/main/ultimatebb.php?ubb=get_topic;f=2;t=031645

Posted by Lady Jane (Member # 7249) on :
 
"Simply" is a sign of poorly written instructions. Clear instructions are always better than patronizing your audience. Words like "simply" just get in the way. There is never a reason to include this word in the steps. It communicates one of two things:

1. When the action is simple, the writer can't be bothered to write concise instructions.
--OR--
2. When the action is NOT simple, the writer wants to audience to think the confusion is his fault.

No one reads every word of instructions, and no one reads them for style. Instead, people scan for key words to find out what to do. Every extra word is a superfluous obstacle. Style is nice, but not a primary concern.

I think people put words like "simply" in for two reasons:
1. They want to assure their audience that the task is not difficult, and
2. They bored with minimalist writing.

There is also a third, less honorable option:
3. The writer knows the instructions are crap and prefers to blame the audience for the resulting confusion.

You can better achieve the first two goals by adding a well-written introduction. A good introduction will give an overview of the task, assure the audience the instructions they are reading were written by people who know what they are doing, and let the writer flash a little style.

--------

</rant>Can you tell I've been editing something that's irritating me?

[ February 08, 2005, 12:46 PM: Message edited by: Lady Jane ]
 
Posted by jeniwren (Member # 2002) on :
 
Kat, do you have any more nuggets of insight like this?

You know I'm writing training manuals for work, right? I'm going to have to go through my work now, you know, and make sure I haven't put "simply" anywhere.

I'm torn between hugging you and running in the opposite direction. [Big Grin]
 
Posted by The Pixiest (Member # 1863) on :
 
On the rare occasion I've used "simply" it was to assure the reader, that Yes, it really IS that easy.

When you can do a complicated task with one small instruction there is a tendancy for people to not believe it.
 
Posted by Lady Jane (Member # 7249) on :
 
*grin* I remember reading that. Sure, what else do you want? I could wax rhapsodic about headings.

*clears throat*

Technical manuals are ALWAYS read in a state of frustration. Unless you are Lorelai and snuggling next to Luke is worth filling the time before sleep by reading the manual for the stove, the only reason people read the instructions is when they have tried it themselves and it didn't work. Usually they have also asked the people around them to see if anyone knew, and no one did. In other words, you are writing for people that are always, always irritated, and they are skimming for the answer. Use headings to identify what they need.

Heading Guidelines
Use a consistent style. For tasks, use the same structure throughout.

For example, all the below are okay, but whatever you choose, choose the same thing every time.
All of those work, although my favorite is "Post on a thread". If I picked that, every task after would be titled as Present imperative verb + prepositional phrase.
--
Pix, I agree with you, but I still think that's better in the introduction or in a note after.

[ February 08, 2005, 01:04 PM: Message edited by: Lady Jane ]
 
Posted by jeniwren (Member # 2002) on :
 
Those are very good, thank you. When I'm skimming for "simply", I'll watch my headings too. Thanks very, very much.

And that reminder about the fact that I'm writing for frustrated people, not people reading for pleasure, is apropos.

[Group Hug] Katie
 
Posted by The Pixiest (Member # 1863) on :
 
Usually when I write instructions for people it's becuase I need them to do something and they're too scared to do it themselves.

For instance:

The exchange database is getting full. Copy some email to a folder and delete the email.

Here's how:

1> go to My Computer, open c: and double click on Email Storage Folder
2> Open Outlook
3> Highlight the mail to copy and hit ctl-c
4> Click on the already opened folder and hit ctl-v
5> In outlook, deleted the highlighted mail with the delete key.

These instructions (with screenshots!) will yield telephone calls asking me to do it for them because they can't figure it out.
 
Posted by Hobbes (Member # 433) on :
 
Yah, I've been trying for a while to write a user's doc for the program I've spent a long time writting and have been failing miserably at it. Sigh, it looks so ugly!. I don't think I ever said simply though. [Smile]

Hobbes [Smile]
 
Posted by Hobbes (Member # 433) on :
 
OK, so I used it three times. I suck. [Frown]

Hobbes [Smile]
 
Posted by Dagonee (Member # 5818) on :
 
I've written many user manuals. Some are references - how to use menu option A, button C, etc. These are easy to write, and very useful to experienced users, but not at all useful to new users. The best manuals for new users, at least for most business apps I've written, concentrate on telling the user how to accomplish their tasks, with software instructions inserted as needed.

It's about writing from the user's perspective rather than the programmer's, and it's distressingly uncommon in custom application development.

Dagonee
 
Posted by fugu13 (Member # 2859) on :
 
Hobbes: DocBook
 
Posted by Lady Jane (Member # 7249) on :
 
Pixiest, I have a guess as to where the confusion for users might set in, but I'm not sure if you posted it asking for opinions or not, so I think I'll wait a moment.

You do NOT suck, Hobbesy. People do it all the time, so it's turned in an instructions meme. I'm doing my best to stamp it out. [Razz]

A friend over Christmas spent about eight hours trying to get the extra monitor to work. For XP, the instructions were "Simply plug it in, and it works." It didn't. This was very frustrating all around. Hard looks were given towards the manual AND the extra monitor.
 
Posted by Mrs.M (Member # 2943) on :
 
I wrote a lot of manuals for my old job and a lot of them were written in frustration, I'm sorry to say. I think I did use the word "simply" a lot.

In my defense, a lot of what I wrote was in response to specific, infuriating situations. For example, I had to write instructions for high schoolers to use our laptops that included things like, "DO NOT place the laptop on a radiator, stove burner, or sink, even if they are turned off."
 
Posted by jeniwren (Member # 2002) on :
 
Pix, I empathize 100%. I was at a customer site last year where I was training a woman who was very accounting-smart but very PC-stupid. It was painful. I couldn't figure out why she was having so much trouble. Then I realized that she was going from her notes, and her notes were, for the most part, wrong or incomplete.

So I stole her notes and rewrote them, organized the same way in "How To..." fashion, complete with screen shots and all that jazz. It was, IMO, a work of art. [Wink] She still couldn't follow them. And though it was way beyond the call of duty on my part, she also continued to complain about how the software sucks. [Roll Eyes]

I decided when starting this project that one of the presuppositions (explicitely stated in the first chapter) is that all users have a working, comfortable knowledge of Windows. It was too hard to think of all the stupid ways to do something so that I could specifically say "DON'T DO X!"

edited to add that I went through all my chapters and couldn't find a single "simply". Yay me!

[ February 08, 2005, 02:36 PM: Message edited by: jeniwren ]
 
Posted by Annie (Member # 295) on :
 
Was it OSC who said never to use "obviously," because if it is obvious you don't need to say so and if it isn't obvious it's rude to say it is?
 
Posted by Lady Jane (Member # 7249) on :
 
Can you tell I'm a little bit bored? Plus, back in school. [Razz]

-------------

Synonyms

My poetry skills died a quiet death when I started doing technical writing, and the slayer was a loathing of synonyms. When writing instructions, synonyms are evil and verboten.

A user who needs help to accomplish a task actually has three jobs in front of him:
1. Find the instructions.
2. Understand the instructions.
3. Complete the task.

If you're writing the instructions, you can't do a whole lot about the third task (unless the project manager is brilliant and has involved the usability people in the software design), but you control the first two.

Synonyms are an obstacle to the second job. Every time you use an unexpected word or construction, you are asking the user to stop thinking about the task they need to complete and instead think about your instructions.

Perfect technical writing is completely invisible - no one ever thinks "Wow, these are wonderful instructions and must have been written by one groovy writer." Instead, half the time the user thinks "What the crap? Not helpful!" and the other half he thinks, "I am so smart. I did that so easily - check me out."

Clear instructions will make the writing vanish and the task clear and simple. One of the best ways to do this is to eliminate all the extra words.

Choose a word for an action, and always use that word. For example, there are many ways to describe highlighting an item from a list, and then clicking the button that submits the selection. All the below are possiblities (although not all are equally good):
My personal favorite is "Select the item from the list. Click Submit.", but whatever you choose, stick with that form. If you pick "select", NEVER use "highlight." It looks like a different action, and then the person has to figure out if it is a different action or else another way to put the same action.
It isn't complicated and it isn't hard to puzzle out, but it makes instructions less clear. It makes the user puzzle out your instructions instead of the task itself. By the time your user reads that sentence, he has done the following:
1. Attempted the task.
2. Failed at the task.
3. Asked the people in earshot.
4. Determined that no one knows how to do it.
5. Found the Help.
6. Found the correct instructions within the Help.
Don't add, for example, "Determined that select, highlight, click, and pick all mean the same thing." to the above list.

It makes for very boring writing, but that's okay. You can make the introduction funny.

[ February 08, 2005, 04:03 PM: Message edited by: Lady Jane ]
 
Posted by AndrewR (Member # 619) on :
 
Here at work, rather than use the word "simply," we say "as can be performed by any competent technician." [Wink] [Big Grin]
 
Posted by Lady Jane (Member # 7249) on :
 
[Razz] Not competent - experienced. Someone who has already been through the learning curve and knows the language.

-------

From the user's standpoint, the computer is NOT an end in itself. It's a tool that helps them to accomplish something (taxes, home design, socialization, world domination), and if it gets in the way of that task, it's not an effective tool. In other words, the users don't care about the computer. Any time spent learning how to use the tool instead of accomplishing the task is time that has been stolen.

[ February 08, 2005, 04:03 PM: Message edited by: Lady Jane ]
 
Posted by advice for robots (Member # 2544) on :
 
When I have to write instructions, I try to include the result of the action so the user knows he is doing it right, plus a little redundancy. To wit:

3. Select the item you want by clicking anywhere on it. A checkmark will appear next to the item.
4. With the item now selected, click the "Conflagulate" button at the bottom of the page. The "Conflagulate" dialog box will appear on your screen.
...

Having a very clear explanation of what this instruction set will accomplish is a good idea. That explanation should include why the user might want to accomplish this task, and exactly how it will help.

As has been said, people turn to the manual when they have specific problems. So the manual should make it easy to locate specific instruction sets. For the customer, finding the section that clearly provides the solution to a specific problem is gold.
 
Posted by jeniwren (Member # 2002) on :
 
Kat, what about capitalization? I have some terms that only mean something within the context of our system. Should they be capitalized *always*, or only in titles? For example, I have properties that are called "Source Master" and "Source List". I'm struggling for whether they should always be capitalized. In the text, it starts to look like a festival of capitalized terms when I'm talking about how to set these things up and how they work together. Or does it make sense to capitalize them in the headings and then put them in uncapitalized italics in the text?
 
Posted by jeniwren (Member # 2002) on :
 
I am, btw, loving the info on this thread. It makes me feel very validated.
 
Posted by MidnightBlue (Member # 6146) on :
 
quote:
Unless you are Lorelai and snuggling next to Luke is worth filling the time before sleep by reading the manual for the stove
Awsome example! New episode tonight! [Party]
 
Posted by Lady Jane (Member # 7249) on :
 
Hmm...afr may have another opinion, but I'd say to capitlize in titles and when you're describing something the on the screen ("Click the Source Master button."), but do not capitilize it when you are discussing the thing itself.

For example, the central processing unit.

Heading: "Choose a Central Processing Unit"
Intro: "Choosing a central processing unit (CPU) involves making the following choices..."
 
Posted by jeniwren (Member # 2002) on :
 
Opinion?

quote:
From Figure 1, we see that a sales order starts the process. Source rules may be set by customer organization (required and considered the default source), customer ship to location, or individual product. The Source Master organizes all the rules into one plan. Within a Source Master, there must be at least one Source List. The Source List is a list of warehouses and/or suppliers from which you may draw inventory or order product. The Source List may have one or many source locations in priority listing, so that when the list is called on, the system knows what order it should start looking for product to fill the order.
or

quote:
From Figure 1, we see that a sales order starts the process. Source rules may be set by customer organization (required and considered the default source), customer ship to location, or individual product. The Source Master organizes all the rules into one plan. Within a source master, there must be at least one Source List. The source list is a list of warehouses and/or suppliers from which you may draw inventory or order product. The source list may have one or many source locations in priority listing, so that when the list is called on, the system knows what order it should start looking for product to fill the order.
This is an introductory text to the concept, so I thought it made sense to capitalize the first occurance of the term, then lower case it from then on in the text. Which seems better?
 
Posted by Lady Jane (Member # 7249) on :
 
Oh, I like the second. [Smile]
 
Posted by jeniwren (Member # 2002) on :
 
Thanks, Kat. I like that one too. 'Course, now it means a lot of editing, because I was really schizo on using capitals. But it will look better in the end, which is all that matters.

Thanks very much!
 
Posted by Intelligence3 (Member # 6944) on :
 
I nearly always capitalize concepts or items that are important to the context of the document. If I was writing something about central processing units for a tech audience, I'd most likely not capitalize the term. But if I was writing for a non tech audience, I would probably capitalize Central Processing Unit. This is by no means a rule of any sort, but in my opinion, it makes the term stand out better for the end user who is not necessarily familiar with the term or is not aware of its importance to the topic at hand.

For example, in a game manual I wrote, the player was accompanied by a squad of soldiers who backed them up. This was called a "fire team," and managing the fire team was an important part of success for the player. Because the term always referred to the player's team of soldiers, I always capitalized it as if it were a proper name. So the player always knew that they needed to use their Fire Team. I feel that it made the concept slightly more clear.

You may experience divergent rates of fuel consumption.

Another tip is that people get information much more easily from bullet lists than from paragraphs. I am often limited in space for software manuals, so I can't use bullets as often as I would like, but really vital information will pop off the page in a bullet list. Don't go overboard, however. If the document is nothing but bullet points, they will be ignored.

• Bulet points stand out.
• Use bullet points.
• Users will be drawn to the information.

Basically, try to keep bullet points surrounded by paragraphs of explanation so they really draw the user's attention.
 
Posted by Intelligence3 (Member # 6944) on :
 
Started my other post then walked away so I didn't see the replies. [Smile]

I prefer the first version. The consistent capitalization immediately identifies "Source Master" as the same thing every time I read it. Also, if there is something on the screen called "Source Master" and it's capitalized, I'd in particular maintain the capitalizaion since the user sees it over and over.

Whatever you do, just be consistent, however. [Smile]
 


Copyright © 2008 Hatrack River Enterprises Inc. All rights reserved.
Reproduction in whole or in part without permission is prohibited.


Powered by Infopop Corporation
UBB.classic™ 6.7.2