“I never knew words could be so confusing,” Milo said to Tock as he bent down to scratch the dog’s ear.
“Only when you use a lot to say a little,” answered Tock.― Norton Juster, The Phantom Tollbooth
I’ll keep this brief.
Precision promotes complexity.
Complexity confounds and intimidates users.
To attract users, you must sacrifice precision to avoid unchecked complexity.
“Precise” implies perfect and complete. You might ask “Shouldn’t we strive for perfect and complete doc?”
I’m advocating imperfect and incomplete doc. I sound crazy. Let me explain.
Perfect and complete sound like virtues; perfectionism and completism less so. Perfectionism means projects smothered by obsessive focus on details at the expense of overall goals. My Google search for “completism” yields “obsessive compulsive disorder” and “the curse of completism” in the first few links.
Useful doc avoids the perfectionist and completist traps. An example is worth a thousand words.
Here’s some extreme precision:
“Step #5: After you have completed the above steps, click the OK button in the lower right corner of the Price Stream Details window to save your changes and close the window. To discard your changes without saving and restore the previous values, click the Reset button in the top right of the window. To discard your changes and close the window, click the Cancel button in the top right of the window.”
Here’s something less precise:
“5. Click OK.
Which is more useful? Which is more approachable? And why does this matter?
Documentation is a beauty pageant. Unless your doc is attractive and approachable, your users will not use it. A 418-page PDF of concepts and procedures is neither. The only users likely to consort with your hulking beast-doc are desperate and resentful. No sparkly tiara and armful of roses for you.
The most perfectly and completely precise content is a waste if users don’t use it.
What can you do to avoid complexity and repelling your users? Here are some thoughts on how you and I can avoid the perfectionist and completist traps.
Keep It Plain
- Use the simplest form of a verb
- Use short, simple words
- Omit unnecessary words
- Write short sentences
― Headings from Federal Plain Language Guidelines, The Plain Language Action and Information Network (PLAIN)
I have to work at this one.
I earned my degree in Pre- and Early Modern Literature, and some stereotypes about English/Lit majors apply. I love words. I love the textures and shades of meaning that I can paint with a rich palette of words.
My natural reflex is to use a million-dollar word or an elegant turn of phrase that I hope precisely captures my meaning.
My users don’t want textures and shades. My users don’t want to meander along complex sentences, pausing to relish the vocabulary I’ve sprinkled along their path.
My users want plain, unadorned meaning and they want it now because they have stuff to do. They are impatient that they don’t know how to do something. Too many words require too much time to process–navigating through them, moving your eyes over them, unpacking their meaning in your brain.
I know better than to indulge my prosaic passions, proclivities, and predilections in my technical writing. If my users need to reach for a dictionary, I’ve definitely lost (and failed) them.
My user-hostile example is extreme but not entirely made up. It reminds me of an exercise in my kids’ middle-school science class:
Given the following materials, write a procedure to make a peanut butter and jelly sandwich:
- Jar of peanut butter
- Jar of jam
- Bagged loaf of bread
- Butter knife
Students usually start with “put the peanut butter on the bread”. The teacher follows the instructions literally and places the unopened jar on the unopened bag of bread. Everyone laughs and the students learn about precise procedures (“open the bag of bread, remove two slices of bread from the bag, lay the slices of bread separately next to each other on the table, etc.”)
Are you thinking “So precision is important now”?
The level of precision appropriate to your audience is important. My example and the sandwich-building lesson both suffer from a lack of baseline context.
The teacher plays a moronic user with no previous knowledge of food containers or food prep. My example assumes the user is a moron with no knowledge of procedures or UIs.
Your users are not morons.
Your users know how to follow a procedure. Your users are familiar with UI conventions, such as Cancel, Reset, and OK buttons. You don’t have to waste your users’ time by repeatedly explaining their function.
Procedural signposts like “after you have completed the above steps” are red flags. Although they add precision by reminding the user about where they are and what they have accomplished, the extra words indicate that the writer is not confident in writing the procedure or that the procedure itself is too long and complex and needs to be reworked.
This sort of overly precise content demonstrates a profound misunderstanding of your users’ needs and risks alienating them.
Align Yourself with Your Users
“What do you do?”
“I write manuals.”
That’s the short answer I give at dinner parties.
Actually, my job is not to write manuals.
My job is to align my goals, my resources, my efforts, and my deliverables so that my users stay happy and successful. If manuals make my users happy, then I produce manuals, but the type of output is secondary.
It’s easy to forget this when working on a complex project under a tight development schedule. Sometimes it’s easier to fall back on the simple stuff, the low hanging fruit, the 80% part of the 80/20 rule.
In my experience, people often conflate precision with accuracy. This is an easy mistake to make, but a dangerous one. Precision is wasted without accuracy.
For example, say you’re flying an airplane over Mt. Rainier at night. Your only instrument is a precise altimeter that indicates an altitude of precisely 4,700 meters. Mt. Rainier stands 4,392 meters tall, so you feel confident and safe in your precision. Unfortunately, your precise altimeter is not accurate and is off by 500 meters. You could be flying at only 4,200 meters. Suddenly all that precision isn’t very helpful.
I’m not immune to this. It’s easier to precisely document all the easy stuff than it is to accurately hit your users’ needs.
And, as another example, I have yet to meet a tech writer who doesn’t hate working on release notes. The pressure, the hectic, down-to-the-wire pace, the unresponsive subject matter experts, the high user expectations, all make for a tough time on the writer.
I’d rather work on a well organized, well presented manual. It’s much more fun and satisfying.
My users don’t care about my tight schedule. My users don’t care what I want. If I gave them a pretty manual instead of ugly release notes, they’d string me up by my toes.
My users care about whether or not their bug is fixed or if the new functionality they requested is in the release or how a new configuration affects their current workflow.
Your users just want what they want. Anything else wastes their time, attention, and good will.
Invest in Design
I spent many years crafting precise doc. I worked hard to avoid imprecision. I wrote and organized content to fill every gap where misinterpretation could take root. For example, my 418-page hulking beast-doc thoroughly documented every aspect of the system to anticipate all possible user issues.
My doc was easy to write because there was little intelligence or design involved beyond “document everything”. I didn’t have to make tough decisions about what content to include and what to omit. In the absence of a guiding design, I developed dictionaries.
I love dictionaries. I miss the journeys of discovery they inspired as you flipped through the pages from “aardwolf” to “zyzzyva”.
The problem with this is that my users have a task in mind. Task-driven users do not want a dictionary. They want a phrase book. They want a lexical cookbook that helps them find the restroom or get to their hotel or purchase a chocolate éclair.
My users don’t care about the etymology of “aardwolf” and they don’t need the definition of “zyzzyva”. They are standing in a Parisian patisserie and they want that tasty chocolate éclair behind the glass. Handing my users a French dictionary and expecting them to translate the words and conjugate the verbs would be stupid.
I still have to work at this, deliberately and judiciously hacking away, leaving possible gaps but also yielding core content that emphasizes usability.
I’ve reached the other side, though, and it feels good.
No Exceptions
There are no exceptions to my rule. You must sacrifice precision where it stands in the way of user acceptance and success–every time.
Because perfection and completion are not possible, you should only pursue perfection and completion guided and moderated by your users’ expectations and needs.
So what happens when you don’t keep your eyes on the prize?
In my first job as a tech writer, I contracted with a company that manufactured equipment for neurologists, doctors who deal with disorders of the nervous system.
The company’s flagship product was a landmark design in neurodiagnostic technology, but it was showing its age and competitors were catching up. The company felt that an update was due and the pressure was on to deliver another home run.
When they introduced their new product, the marketing hype reached the level of Apple’s “1984” campaign for the Macintosh. The new machine revolutionized the doctors’ workflow, doing away with the old, cluttered, modeless interface (a button for everything and everything has a button) for a streamlined, modal interface (fewer buttons, uncluttered, and sleekly presented).
The doctors hated it. The company fell on hard times and was acquired soon after.
Their new machine was a lot like my 418-page hulking beast-doc: well meaning but misguided, impressive at first glance, but terrifying and repulsive if you had to use it.
What went wrong? They didn’t follow my guidelines.
- Keep It Plain: The company traded “physically complex but procedurally simple” for “physically simple but procedurally complex”. In the old UI, a single button performed a common action. In the new UI, that same action required multiple button clicks to navigate through several menus. They didn’t keep the procedure plain and simple. The doctors and their technicians recoiled like salted slugs when they recognized how their days of running tests and getting results (and making money) would turn into days of navigating menus.
- Know and Trust Your Audience: The company didn’t know their audience. They thought they were designing for the equivalent of iPhone users when their customer base was actually more like veteran Linux wizards making a good living with their command-line skills.
- Align Yourself with Your Users: The company felt the pressure to outdo their competitors and they fell in love with a UI design fad. These factors blinded them to their users’ needs.
- Invest in Design:> Here the company did the right thing for the wrong reasons. Design came first, but without user-based guidance, their precise design steered them directly into a mountaintop.
There She Is…
Ultimately you must decide how you define perfection and completion. What standard of beauty do you apply in the doc beauty pageant?
If you’re driven to precisely document every aspect of your product completely and then turn that documentation on your users like a firehose, then you and your users are going to be unhappy. At some point so will your employer.
If your content and delivery leave gaps but perfectly match your users’ expectations and completely meet their needs, then you’ve won. You can wear your sparkly tiara in the office with pride.
