Category Archives: simplicity

Reverse engineering

Posted on by

Reverse engineering is the process of analyzing something to understand its composition and how it works, often with the intention of copying it.

A notable example is Compaq computer’s reverse engineering of IBM’s ROM-BIOS (the chips that made IBM computers work) in the 1980s. By methodically determining how the chips functioned, Compaq was able to clone the IBM PC, and produce computers that could run IBM software.

The analysis of the human genome is a more intriguing example of reverse engineering. By determining the makeup of the entire human DNA sequence, scientists hope to someday cure diseases by creating customized medications targeted to an individual’s DNA; no two people would receive the exact same treatment.

Image result for UnabomberA fascinating application of reverse engineering to communication is forensic linguistics: the science of language analysis to solve crimes. The FBI used it to identify the Unabomber, who demanded his 35,000 word manifesto be published. As a result, his own brother recognized the style of writing, leading to the Unabomber’s capture and imprisonment.

Effective communication is a form of reverse engineering. It is the process by which a communicator determines what a user is trying to achieve, then works backwards to create the information in a form that the user understands and can easily act upon. (I call this the “back-words” approach.)

All users are ultimately trying to achieve something by solving a problem. Specifically, they need to:

  • complete a task
  • understand a concept, or
  • look up something

Therefore, all documentation must solve a problem. By applying the principle of reverse engineering, we can solve these problems. In these examples, we’ll explore the problem everyone loves to hate: filing their taxes.

Problem 1: Completing a task

A user who must complete a task does not want to complete it – they want the end result. Therefore, to effectively document a task, a communicator must:

  1. Understand the end goal and the purpose behind it.
  2. Know the main steps (and any alternate steps) to achieve that goal.
  3. Document the steps as quickly and efficiently as possible using the language that the least experienced user will understand.
  4. Clearly state the end result.

Image result for tax returnApplying this to tax filing, the documentation (or the process itself) must:

  1. Recognize that the user wants to pay as little tax as possible; they don’t want or need anything else.
  2. Guide the user through the various steps, offering appropriate guidance to minimize the amount payable.
  3. Clearly indicate if the user owes an amount or will receive a refund.

Problem 2: Understanding a concept

A user may just need to understand something. For example, the tax filer may want to know about a specific tax deduction that they may be entitled to. However, even in this case, they are still trying to achieve the same goal: minimizing the amount of tax paid.

Therefore, to effectively document a concept, a communicator must:

  1. Understand the reason why the user wants to know this particular concept or idea. That is, they must understand the understanding.
  2. Describe the subject clearly and in terms familiar to the end user. There’s nothing more frustrating to a user than something that is described using terms they don’t know.
  3. Offer advice about practical steps they can take based on this knowledge, or additional resources.

Applying this to tax filing, the documentation or process itself must:

  1. Again, recognize that the user wants to pay as little tax as possible.
  2. Explain each deduction and whether the user qualifies for it.
  3. Guide the user on applying for the deduction they qualify for or explain why they don’t qualify.
  4. Offer information about additional deductions that they may qualify for.

Problem 3: Looking up something

A user may need to retrieve a specific piece of information in order to solve one of the two other problems stated, which, in turn, enables the user to achieve their goal.

To effectively enable the user to look up something, a communicator must:

  1. Organize the information to make it easy to search, using a clearly identifiable search tool.
  2. Present clear and meaningful search results, and filter out meaningless ones.
  3. Understand the ultimate reason why the user is conducting this search.

For example, if a user is claiming medical expenses, they want to know which expenses they qualify for. They would then use this information to claim these credits.

Therefore, when searching for a credit, if the user finds an applicable credit, there should be a link to the information or process that will enable them to obtain this credit. The point is that the user is not searching to find out which deductions apply; they are searching to save money.

Summing up, a user needs to:

  • complete a task: that is, DO something
  • understand a concept, that is, KNOW something
  • look up a piece of information, that is, FIND something

for the ultimate purpose of achieving a goal.

This can be further summed up as:

DO/KNOW/FIND -> ACHIEVE

Reverse engineering this, we get:

ACHIEVE -> DO/KNOW/FIND

This formula states that all users want to achieve something, by doing, knowing or finding something. From the user’s perspective, the achievement (or end goal) is the key. How they get to that goal is nowhere near as important as the goal itself.

Stated differently: millions of people own drills that they didn’t want.

What they wanted were the holes.

 

1

Advertisement

Trinity, One Two Three

Posted on by

People are innately drawn to things in threes; to objects in triplicate. There’s the classic Christian trinity, where God is divided up neatly into three parts: the father, the son, and the holy spirit. But there are many other trinities:

  • mind, body and soul
  • thinking, feeling and acting
  • work/life/play balance
  • the division of pregnancy into three trimesters
  • animal, vegetable and mineral
  • Christians, Muslims and Jews
  • protons, neutrons and electrons
  • the First, Second and Third Worlds
  • sex, politics and religion
  • family, friends and co-workers

In addition, Starbucks Coffee developed the idea of “the third place” outside of home and work, where one could simply relax while drinking $6 lattes. Clearly, people are attracted to threesomes, but why?

It could be that three represents a careful, comforting and symbiotic balance. While it’s true that just two things can “balance” each other (picture two equal riders on a see-saw), extending the number to three seems to add that extra element of desired symmetry. Each of three balances out each other in a psychologically pleasing way.

DITA, an XML markup language that is revolutionizing how content is stored, created and managed, also uses a trinity. In DITA, all content is stored as individual, modular topics. There are three basic DITA topic types in which all content can be classified: concepts, tasks, and references.

  1. A concept topic describes what something is or why you would perform a task. It gives the idea behind something; the background information that the reader needs to know.
  2. A task topic gives detailed, step-by-step procedures for a specific action. It can include pre-requisites and expected results. It is one of the most common topic types.
  3. A reference topic contains technical material, specifications, lookups and other detailed information, often in a table form. Examples include command references, allowed values, lists and catalogues.

Now, what’s very important to remember is that you should never mix the content of each of the parts in this holy trinity together, for you will surely burn in content management hell.

For example:

  1. In a task, do not include a detailed explanation of why you would perform this task. Maintain this background information in a concept, then, if necessary, link it to the task topic.
  2. In a concept, do not include procedural steps. Keep these steps in a task topic.
  3. If there are many possible values to choose from in a task, do not include them in the task, but in a reference topic instead.

You can see, therefore, that this trinity of topic types covers all your information needs.

And it’s as easy as 1-2-3….

The PowerPoint from Hell

Posted on by

General Stanley McChrystal, head of U.S. and NATO forces in Afghanistan, has provided a perfect example of how not to create document: a PowerPoint slide that purports to explain the U.S. military strategy in Afghanistan.

Related image

“When we understand that slide, we’ll have won the war,” General McChrystal said. In other words, never. This image is the worst example in history of spaghetti documentation.

Now, compare that monstrosity with a simple document created internationally renowned tax expert Dr. Alvin Rabushka at Stanford University.

Dr. Rabushka has proposed a 15% flat tax for Canada. This would collect the same amount of revenue that the government currently collects, without having to wade through multi-page, hyper-complicated tax form documents and software.

The good doctor even designed a form the size of a postcard that could be filled out in about five minutes.

It’s estimated this simple document could save Canadians $30 billion when you factor in:

  • the time and effort spent getting receipts and preparing tax returns
  • the cost to hire accountants and lawyers to sort through the massive tax code
  • the cost to employ vast armies of tax collectors their support staff

I can think of no two documents with more different content and results.

The PowerPoint explains nothing, saves no money and may even indirectly contribute to the war’s endless multi-billion dollar cost by giving the illusion of comprehension to an incomprehensible situation.

The tax form is clear, simple and explicit, and would save billions of dollars.

Which document would you prefer to manage?

Complication Nation

Posted on by

Related imageI’m getting emotional over motion. “Motionflow” TV must be one of the dumbest inventions ever. Oh, it sounds great in theory: a video display technology which reduces the blurring of rapid motion, making it flow more smoothly. The problem is it works too well. Watching a movie on a MotionFlow TV makes the film look like a cheap video. I mentioned this to a hapless TV salesperson – his feeble response was that you could turn off this so-called “feature”. (To be fair, MotionFlow is probably best for sports and live TV, but I’m a movie guy myself.)

MotionFlow is a symptom of a bigger problem: companies designing products crammed with features that people either don’t need, don’t want or can’t use. Ever tried to buy a cellphone that only makes phone calls, or a printer that only prints? You’d have better luck getting through to a live tech support person in less than two minutes.

The “overcomplication” problem hits our profession in two ways. First, in the tools we use. Yes, there are many good authoring tools out there. But many of them have far more features than you would ever need. For example, I have yet to find a simple, off-the-shelf, easy to use XML publishing system, one that would let you quickly create documents, TOCs, and indices, and publish them to a content management system. (If you know of one, let me know.)

More importantly, “overcomplication” is a problem in documentation. I’ve seen many documents that have far too much information in over-sized topics that are difficult to read. That’s why I admire quick start guides. They give users the essential information they need to set up and use a product. The other content can be moved to a regular user guide or reference guide.

So the next time you’re thinking about getting the latest version of Super-Duper Authoring Tool Version 127.3, or releasing a fun-to-read 800 page user guide, don’t go with the flow; instead, de-complicate.

Un-super Size Me

Posted on by

Image result for supersize meIt’s astounding that the very people whose job it is to be concise fail to be concise on their most important document: their resume. I plead guilty to this word-crime.

After consulting with an expert, I reduced my resume from 650 words to 300. How? By hacking off the crap that had accumulated over the years, and then simplifying the leftovers.

My resume is now a page and a half and can be read in 20 seconds. Considering the mountains of lengthy resumes employers must sift through, a short and concise one is a breath of fresh air.

Isn’t this extreme editing? Yes, it is. Try it; you can always back up your super-sized resume.

Tech Writing, From A to Wii

Posted on by

My wife asked me if we’re ever going to buy a game console. In my worst French I mumble, “Oui“. “We’re getting a Wii!?!” she cries, ” Woo-hoo!” I cannot Undo my misunderstood utterance.

The good news is that Nintendo recently lowered the price of its popular gaming unit. The bad news is that the unit represents only a fraction of the total price. Once you’re done adding accessories (such as the Wii fitness board, extra controllers, other games, extended warranties and taxes, you end up with a purchase price approaching that of a small car. But, oh boy, is it worth it.

A brief disclaimer – neither I, nor any of my relatives, friends, or enemies work for Nintendo. However, I sure wish I did.

The Wii is a masterpiece of design, form and function. That’s why it’s outsold the Xbox 360 and PlayStation 3 combined. I don’t even want to discuss the documentation that comes with Wii, which is adequate, but the fact that most users won’t even need the guides. (Gulp! No tech writers needed?!)

The I’s Have It

The Wii succeeds because it has the magic combination of I’s:

  • Intuitive – it’s easy to use
  • Informative – it gives clear and simple instructions as you’re using it
  • Intelligent – it appears to “learn” from your actions
  • Incredible Interface – based on all of the above

A huge factor in the Wii’s success is its simplicity. The remote only has a few buttons. The games, aimed mostly at families and non-power users, are generally simple to learn and play. That is, the user does not have to struggle with the hardware or software to learn it.

Am I Making Myself Clear?

Every professional communicator (including us technical ones) can learn from this. Readers should never have to struggle to find the information they’re looking for, or understand the information you give them. It should be as clear as glass.

Beyond documentation, technical communicators have a critical role to play in product design. I’m fortunate to work for a company that actively solicits feedback from its employees, and have given numerous suggestions for enhancements to the user interface. No formal training is required for common sense suggestions, such as the fact that every field should have a name, and that the name should be clear and self-descriptive.

Always be on the hunt for superb design and execution, as seen with the Wii. It can inspire you to create great documentation.

Now, back to tennis and golf…

Microwaveable Message

Posted on by

Related imageI’m annoyed with the writer who developed the message that appears on my microwave when it’s finished cooking. The message is: ENJOY YOUR MEAL.

Maybe I’m not cooking a meal – maybe it’s just a snack. Maybe I’m heating up a drink or a small, defenseless animal. Maybe I don’t want to enjoy my meal. Besides – how can an appliance wish enjoyment on anyone? I thought only higher mammals could do that.

On top of all this, it takes an agonizing five seconds to display the message because it has to scroll the letters vertically and can display only about five letters at a time. Five seconds to a normal person is five hours to a tech writer.

If I’d been the tech writer on this job, here’s the message I’d have written:

DONE

Now I’m done with this blog entry.

The Matter of Dark Text

Posted on by

Physicists have many odd ideas, but one of their oddest surely is dark matter. It is the dense, invisible stuff which fills the universe, but its existence can’t be proven directly, hence the term dark. It also has a sister: dark energy. Dark energy, like dark matter, is also invisible and cannot be directly proven to exist. However, dark energy appears to explain why the universe is not only expanding, but doing so at an accelerated rate.

Scientists are working hard to find out which of these two things is more abundant in the universe. If there is more dark matter than dark energy, then the gravity of the dark matter could eventually cause the universe to stop expanding and then start shrinking, collapsing into a single point, in a very noisy event called a “big crunch”. Alternatively, if there’s more dark energy than dark matter, it could mean that the universe will continue to expand but, like spots on an expanding balloon, everything will be pulled further and further away from each other, resulting in a very cold, lonely universe.

The good news is that either scenario won’t happen for billions of years. The bad news is that in either case, all living things will cease to exist. To paraphrase Einstein, “Bummer.”

Fortunately, the other two qualities of our universe, space and time, don’t have a corresponding “dark” component; that is, there’s no such thing as dark space or dark time, except perhaps on Star Trek. However, there is a corresponding component in our profession, and it is called dark text.

Dark Text Matters

Dark text refers to the many layers of hidden meaning in any text segment. It ranges from the implied meaning that the author intended, or that the reader infers, to much deeper, more hidden meanings.

Here’s a simple example:

To print a document, click Print.

The dark text of this step is:

  • a document is a piece of paper
  • you’ll need a printer to print something
  • “clicking” involves position the cursor on a monitor over a certain graphical element
  • the printer must be connected to a computer and must be configured correctly

Darker text could include:

  • you should be careful before you print something: once it’s printed, you can’t “undo” it
  • the printer must have toner and paper; electricity would also be helpful
  • if you can’t figure this out, call your 11-year old relative who knows more than you do about computers

There’s Nothing Funny About Funny Money

Here is a more interesting example. In stores, you often see this sign:

We do not accept $50 or $100 bills.

The first level of dark text is derived from the fact that this statement does not explicitly tell the reader what to do or not do. So the “obvious” (or lighter) dark text is:

Don’t even try to give us $50 or $100 bills.
The next level of dark text is:

We don’t want counterfeit money, which typically is $50 or $100 bills.

However, there is a third level of dark text, which is darker (and more sinister) than these two other levels.

Because we don’t accept $50 or $100 bills, we will accept $5, $10 and $20 bills, even if they are counterfeit.

This, in fact, is exactly what has been reported by the authorities. Counterfeiters know that unless stores are checking every bill they get, they will simply assume the lower denomination bills are legitimate. These stores have inadvertently given a sign to these criminals that they will take their fake money.

What, then, should the sign say, to scare away any potential counterfeiters? Perhaps something like this:

WARNING! We check all paper currency to make sure it is not counterfeit. If you try to use counterfeit money here, you will be caught and prosecuted to the fullest extent of the law. Punishment can include a major fine and imprisonment for up to 14 years.

Note that most of the dark text has been removed. This is what is known as “writing from the user’s perspective”.

* * *

As technical writers, we must be aware of dark text, and where possible, try to minimize it. It’s true that we cannot possibly document all of the hidden meaning in text, nor should we. Still, much information may be hidden or very subtle and must be exposed or more clearly stated. To decide when to expose dark text, you need to ask yourself:

Would a typical user need to know this fact in order to more effectively use the thing I am documenting?

The goal is to give users all the information they need to do their jobs, and no more than that. This is an axiom of technical communication, and will be so until the end of the universe.

Extra Sweet Instructions

Posted on by

I’m in a fruit phase this month. I recently wrote about watermelons; this article will discuss pineapples, for I am equal opportunity fruitist.

Here’s the instruction manual that came with a pineapple I bought:

(You definitely know you’re different from normal people if you find yourself scanning fruit instructions.)

This is documentation at its most elegant. No words. Just pictures. Slice, dice and enjoy!

Size Matters

Posted on by

Image result for small medium largeIf you’ve been following this blog to any degree, you’ll have noticed I write three types of articles:

1. Small
2. Medium
and, last but not least,
3. Large

The size of the article is directly proportional to the number of words required; no more and no fewer. (This, by the way, is a general principle to follow in technical communication.)

It’s like food: sometimes you just need a snack, other times a regular meal, and, once in a while, an enormous, gut-bursting, three-belt notch loosening meal – the latter popular during this holiday season.

Enjoy this snack. More delectables to follow.