- Topics would have no context or structure.
- Concepts would have no meaning.
- Indices would include non-existent entries.
- Tables of content would cease to exist.
- Tasks, the backbone of many user guides, would describe inaccurate or irrelevant steps, and would omit key steps.
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.
- 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.
- 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.
- 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.
- 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.
- In a concept, do not include procedural steps. Keep these steps in a task topic.
- 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 world is mourning the death of Steve Jobs, founder of Apple. He has been hailed, quite rightly, as a creative genius, a brilliant and revolutionary designer, and a bold visionary who completely transformed the world of personal technology. (Full disclosure – my first computer was an Apple IIc, way back in 1985. It was also my last.)
As brilliant as Jobs was, he was also stubborn, arrogant, and an extremely demanding perfectionist who was openly abusive towards his employees. In fact, his arrogance and hubris probably killed him. He refused medical treatment for nine months, insisting on treating his cancer with diet, acupuncture, herbal remedies and a psychic. This delay most likely shortened his life.
Jobs was influenced by Buddhism, which explores the connection between mind, body, and soul. Given how cruel he could be to others, and his frequent violent rages, one could say he had a “cancer of the soul”. Buddhism suggests that a disease of the soul can morph into a disease of the body. It’s a medical fact that some diseases have a psychological basis. Whether this was the case for Jobs, we will never know, for he now resides in the iCloud.
(Speaking of life and death, we now know why Apple devices don’t have an on-off switch. Jobs felt that an off switch represented death. It symbolized for him the terrifying prospect that we’re all machines that simply “power off” at the end of our lives.)
These observations are not meant to criticize or judge, but to point out that no-one is perfect, and that there is more to a person than their technical abilities.
An Untechnical Communicator
A technical communicator may be a technical genius, like Jobs. They may have extensive experience managing a wide variety of complex documentation, thorough knowledge of all the major tools, and can speak twelve languages, human and computer. But if that person comes across as arrogant, obnoxious, highly critical of others and emotionally unintelligent, they will not succeed at job interviews. Even if they do land a job, they may have a tough time keeping it. Jobs himself was fired from Apple, and it was a long road back for him to regain control.
I’ve had the misfortune of knowing a few individuals like these. In the end, they either change or they go, or else every who works for them goes!
All of this means that you can win a job in an interview even if you are not the most technically qualified. The truth is that most software apps can be learned in about a week or two. The more difficult skills to acquire are non-technical:
- interviewing and listening
- working well with others
- oral communication/public speaking
- time and project management
- objectivity, seeing the “big picture”
- being open to criticism
- handling change, conflict and stress
- creativity, flexibility and adaptability
If you can show that you have these skills, and a genuine passion for the job, this will greatly increase your chances of getting it.
Research? We don’t need no stinkin’ research!
It’s interesting to note that Apple conducted no market research – no focus groups, no interviewing, no surveys – nothing. They simply designed products that they thought were cool and useful, then unleashed them on the public.
This seems to contradict to one of the tenets of our profession: to actively design with the end user in mind based on their needs and wants. Presumably, this involves working directly with our readers and having them test our documentation to see if it’s useful.
The problem is that we often don’t have the resources to do this. The good news is that we don’t have to, for reasons that are similar to those at Apple.
Users ‘R Us
The fact is – we are users. We should have a good idea of the kinds of information our users want, and the way it should be presented.
When you need information, you want it to be clear, understandable, and easy to find and use. That is precisely what our users want.
Jobs believed it was meaningless to ask customers what they wanted because they didn’t know what they wanted! This was true because the products Apple created were so different from anything that the users had previously experienced. How could users be asked about something for which they had no form of reference?
In many cases, our customers may not know exactly what information they are looking for. The example I always like to give involves the mail merge process.
That Mail Merge Thingamabob
If you were documenting the mail merge process for a novice user who had never even heard of it, you couldn’t simply create a topic called Mail Merging, with a corresponding mail merging index entry. Instead, you’d need to think about all the ways a user could refer to what they want to do, and then frame the topic accordingly.
For example, you might title the topic: Creating Multiple Personalized Copies of Letters and Other Documents or Personalizing a Document that is Sent to Several People. Your index entries could include:
- addressing one document to several people
- copies of one document, customizing
- customizing a document to be sent to several people
- different names, entering on a document for several people
- documents, individually addressing to several people
- mailings, sending customized documents to several people
- mass mailings, performing
- multiple copies of a document, personalizing for each person
- names, changing each on several copies of one document
- personalizing one document sent to several people
- sending one document to several people
- single documents, changing the name on several copies of
- specifying different names on several copies of one document
You should be able to develop an extensive list of index entries like this without having to ask the user first.
But take great care with each entry – because one bad Apple can ruin the whole bunch.
Who among us would not strive to be that most self-actualized of persons, master of many fields, an intellectual powerhouse, knowledge warrior and universal genius known as a Renaissance Man.
A Renaissance man (or woman) is not simply a jack (or jill) of-all-trades. It’s someone who has an outstanding talents in, and great knowledge of, a wide variety of areas. Leonardo da Vinci is the classic example. He was an exceptional artist, scientist, engineer, inventor, and so much more. He was intensely curious and had a tremendous imagination: the ultimate technical communicator. Using his plans, many of his inventions were reconstructed in modern times and performed well.
Technical communicators are not just technical, and we do far more than communicate. A true technical communicator is a Renaissance communicator, as our talents involve many other professions and fields of knowledge.
Renaissance Communicators are:
- artisans designing, formatting and shaping words and images, as well as sound and motion in instructional videos
- teachers imparting information to others in a manner so subtle and seamless that our students don’t even realize they’re learning something
- architects designing and building complex informational structures
- physicians healing incomplete, incorrect or inaccurate documentation
- detectives piecing together clues to solve the mystery of the product we document
- translators and interpreters of the meaningless into the meaningful
- magicians turning chaos into order and creating guides out of thin air
- craftspeople building, tweaking, and endlessly tinkering with our data creations
- cartologists of information mapping the big picture of a product or service
- code-breakers decoding incomprehensible gobbledygook into meaningful prose
- archaeologists hunting for buried informational treasures
- ambassadors between those who create products and those who use them
- journalists persistently pushing, prodding and probing our subject matter experts with the tough questions
- soldiers in the war on error and confusion
We are the true multi-taskers, knowledge workers, and service bureaus that willingly absorb the pain of misinformation, disinformation and no information to create informational works of art.
Not only are we Renaissance Men and Women, our profession itself is undergoing a renaissance, as technical communication processes move toward separating form from content.
It’s a Renaissance, man.
Quick quiz – can you name the seven deadly sins? And no, Dopey and Grumpy do not count.
The seven deadly sins are:
and (my personal favourite)
I would have loved to have been on the committee that chose these sins above all others. (“If you vote for lust, I’ll give you pride and sloth.”) In any case, the final list is as good as any, and remains quite popular, as popular as the sins themselves, unfortunately.
An easy way to remember these sins is to use a “leggs password”. Taking the first letter of each sin and rearranging them, we get LEGGSPW – or “LEGGS PassWord”. Be sure to write that down.
The seven sins, one for each day of the week, were well-documented in the 1995 film, Se7en. It is one of the darkest films I’ve seen, both literally and figuratively. We enter a nightmare world in which an insane serial killer with a God complex murders his victims according to the seven deadly sins. The twist ending is so disturbing that to this day, I still shudder whenever I see a courier truck. (Those of you who’ve experienced this film will know what I mean.)
On a lighter note, they say when life gives you lemons, to make lemonade. Since I’m not a preacher, I won’t attempt to dissuade you from carrying these sins into the world of tech comm. Playing “devil’s advocate”, these sins, if implemented constructively, can actually make you a better communicator. Rather than being deadly sins, they can be quite lively.
Let’s start the sinning…
The greatest quote about greed is in the film Wall Street, when the ruthless mogul Gordon Gekko makes the following statement:
Greed, for lack of a better word, is good. Greed is right, greed works. Greed clarifies, cuts through, and captures the essence of the evolutionary spirit. Greed, in all of its forms; greed for life, for money, for love, knowledge has marked the upward surge of mankind.
“Greed for knowledge” – amen to that. Greed for knowledge, information, clarity, consistency and simplicity. If you’re not greedy for these things in your work, it will burn in the hell-fire of bad documentation, and that’s a real sin.
We should all take pride in our work, but not be boastful. We have to humbly and sincerely recognize we technical communicators are just like everyone else – only better. For what other species of humanity is as sensitive to words and meaning as we are? We are the patron saints of clarity, simplicity and functionality.
I admit I’m a glutton – not for food, but for information. I devour newspapers, magazines, books, blogs, websites, signs, posters, and even junk mail. I stuff my mind with it until it’s bursting. It’s alot to digest, but there are lessons to be learned (and great ideas to be stolen) from all of it.
When you see a beautifully designed quick start guide, a well-organized manual, a perfectly arranged help system, a clear and simple procedure, this should turn you on. If it doesn’t, there’s a malfunction in your informational libido, your user manual mojo, and you must see a Doc doctor immediately.
Sloth is such a destructive sin that there’s really no way it can be useful in communication. Its only value is recognizing it in others. Non-writers and lazy writers who produce bad documents are “slothful”. They should anger us into action, empowering us to clean up their messes when called on to do so.
Users can also be slothful, but since they are paying our salaries, we have to be more forgiving. Design your documents so that even the laziest user can get the information they need, quickly, easily, and with minimal effort. They should be able to fly through your document as they lie on their couch, doughnut in one hand and TV remote in the other.
Envy is the honest way of stating you have a desire for change. To be a great communicator, read the works of great communicators, and ideally meet them. But don’t just admire them – envy them. Then become the type of communicator that others will envy.
It’s easy to pour our wrath onto those who think they can write but cannot; on engineers who create error messages such as Error 43 – Big. You have failed.; on marketers who use strange words and phrases like actualize, customer-centric and out-of-the-box thinking; on reviewers who mark up a 400 page draft with just two words: Needs work.
How simple life would be if we could just release our fury onto these people. However, living in a somewhat civil society, we are precluded from most acts of violence. Instead, let us direct our fury, our anger, our wrath towards the documents themselves. Documents are so much easier to change than people.
So let us take these broken and bruised clumps of information, and with all our might and energy, reshape them into clear and meaningful documents.
Let there be no mercy, as we unleash in full force our technical, communicative, organizational and design skills onto our work.
Let us be…wrath.
And may God have mercy upon the soul of the document that we are about to remake in our image.
The ancient Greeks believed that everything in the world was made up of four basic elements: Earth, Water, Air, and Fire. This concept was so powerful it lasted even through the Renaissance. Interestingly, the first three elements correspond directly to the three states of matter: solid, liquid, and gas. The fourth element, Fire, corresponds to energy. Given that matter and energy are the two main elements of the universe, the ancient Greeks were not far off in their view of the world.
Aside from the physical aspects of these elements, there is the meta-physical. Earth, being solid, represents stability and tangibility – that which can be touched, seen and known. Water, being liquid, represents change and movement. Air is invisible and therefore less tangible – we cannot see it directly but can see its effects. Air is also the medium required to support Fire, and life itself. Fire is pure energy that can change matter from one state to another. It can thaw ice, converting it to liquid water, then to steam, a gas.
Aspects of these four elements exist in technical communication. Earth is the visible, stable portion of a document – the portion that can be seen and which rarely changes. A printed manual is forever Earth – never changing until replaced by a newer version.
With more documentation now online, information has shifted in form from Earth to Water – ever flowing, ever changing, and increasingly customized and shaped towards the specific needs of the end user.
Air is the medium through which documentation is delivered. The printed page, the monitor, the smart phone, the tablet – the medium is not the message but is the air in which it lives. Air is also the white space around all words, text and images, allowing the words to breathe. With no medium or no white space, communication would be starved of life.
Fire is the energy that flows through the mind of a technical communicator, allowing them to shape, bend, twist and change the words and images they yield. It is the transformative power that a skilled communication craftsman uses to alter the form and substance of information. For a spectacular of Fire, see the CSS Zen Garden, where stylesheet magicians forge communicative works of art, as swordmakers used to forge metal in fiery furnaces.
Air. Fire. Earth. Water.
Note the words formed by the first letter of each element: AFEW.
All you need is “a few” elements to create a universe of communication.
These kits cost $60 and contain a plastic bag that fits over the head, a plastic tube for attaching to a tank of helium gas, and detailed instructions.
Although Oregon allows doctors to help terminally ill patients end their lives, it certainly has not legalized suicide for mentally ill individuals. The fact that anyone can easily purchase these kits has spurred the government into action.
This very sad case raises a disturbing thought experiment for information developers:
Imagine you were forced, under threat of death, to develop the user guide for this suicide kit. You are given all the technical specifications and procedural information, but you have permission to write any text you wish. You know that some of the users are not terminally ill, but are instead depressed.
What information would you include in your guide, which is literally a “life and death” document?
Knowing our users, we would include a warning such as:
WARNING! This kit is only intended for people who are terminally ill. If you do not have a physical illness, or think you might be depressed or suicidal, please call 911 or the local suicide prevention number….
Now imagine the same scenario, but this time the manufacturer of the kit must approve your draft. They have told you that you cannot include any type of warning for depressed people. If you do, it will be deleted.
Now what do you write? How do you give a user information without explicitly stating it? Simple – by implicitly stating it, as follows:
Note: This kit is only intended for patients that have been diagnosed by a doctor as having a painful and terminal illness.
The irony here is that this note could be more effective than the traditional warning. It does not explicitly tell a depressed user what to do. Instead, it subtly suggests that this guide does not apply to them. It plants a seed that could save the user’s life.
Returning to the real world of ordinary documentation, we often have to balance what a user wants to know against:
- what a user needs to know (even if they don’t want to know it)
- the requirements of the manufacturer
This nightmare scenario of the suicide kit guide illustrates how difficult it can be to balance these competing needs and wants.
Now, most users ignore documentation, and certainly most depressed people would ignore both the warning and the note. But not all of them will, and if the inclusion of this paragraph saves only one life, it will be worth it.
As the Talmud, the ancient book of Jewish law, states:
Welcome to the Chinese Tent…
Imagine a large tent, and in it, a person who speaks only English. We’ll call this person the respondent. Outside the tent is a person who speaks only Chinese. We’ll call this person the questioner. The questioner writes a message in Chinese and passes it to the respondent through an opening at the front of tent. The respondent receives the message, then using an infinitely complex look-up system, matches the message on the card with a corresponding card containing a response in Chinese. The respondent delivers the pre-written response back to the questioner.
From the perspective of the Chinese questioner, the English respondent has read the message and understood it, demonstrating intelligence. However, has the respondent actually responded intelligently? Remember, the respondent does not understand a word of Chinese – he has simply matched up a pre-defined response to the received message.
This is not intelligence, but an elaborate forgery. The Chinese Tent exposes the folly of thinking that computers can actually be intelligent. Computers can simulate all sorts of reality; this does not make the reality they simulate real.
When a computer runs a virtual stock market exercise and makes millions of virtual dollars, the user does not become wealthy. When a computer runs a weather simulation that has 40 cm of rain falling in one day, the user doesn’t get wet. Yet when a computer simulates intelligence, we all rush to believe it’s actual intelligence, and not a pale imitation.
It all comes down to definitions, something technical communicators are very fussy about. So how do you define intelligence? Here’s one standard dictionary definition:
The key word here is understanding, which implies consciousness; the knowledge that one exists. This is something that computers simply don’t have.
However, if you define intelligence as the ability to give a meaningful response to a question, then computers could indeed be intelligent. A recent example of this was Watson, a super-computer developed by IBM. Watson was a contestant on the Jeopardy game show, beat his human opponents and won a million dollars.
Depending on the definition of intelligence you choose, Watson is intelligent or simply another version of the Chinese Tent. It is able to analyze questions and supply responses, but if you were to ask it how it felt about winning against humans, it would have no response.
- What is this object, thing or concept?
- What is it used for? Why would I use it?
- How do I perform a specific task?
- What are specific things I need to be aware of?
- What things or tasks are related?
An effective document, then, is one giant answer book. An intelligent document gives the user the answers they need, without the user even realizing the effort they made to find them.
Imagine this scenario: a runaway train is hurtling towards five people tied down to a railway track by a madman. You can pull a switch to divert the train onto another track where another person is tied down, killing the one person, but saving five.
Should you throw the switch? Most people will say yes, reasoning that it is better for one innocent person to die than five.
Now imagine this scenario: The same train approaches the five trapped people. This time, you are standing next to a fat man on a bridge over the tracks. If you push the man onto the tracks, his massive weight will stop the train but will kill him. However, the other five people will again be saved. So, do you give him a push?
Most people will say no, because even though the end result is the same (the man will be killed), the killing will be direct and deliberate. In the first scenario, killing the man is an indirect effect of pulling the switch.
You can vary this scenario endlessly. What if the fat man was also the mad man? What if the one person tied up was your spouse, parent or sibling? What if the five men were all convicted murderers who had escaped?
All of these scenarios are part of the trolley problem. There is an entire science devote to ethical and psychological issues called experimental philosophy, or X-Phi and even Trolleyology. Experimental philosophy uses data gathered through surveys of hypothetical moral scenarios. It’s a scientific attempt to draw conclusions on how people reach moral decisions. In doing so, X-Phi is a strange brew of science, psychology and philosophy.
X-Phi is not just a serious of extended thought experiments: it has very practical applications. For example, the recent financial meltdown was caused by many people making various choices and judgments. These people included not only the lenders and administrators of high risk loans, but the recipients of these loans, and the various government agencies involved in regulating the loans. All these people made what in hindsight are appallingly bad choices. However, at the time, these choices may have seemed quite reasonable. By studying the factors that lead people to make bad choices, the hope is they won’t make them again.
Technical communicators are often faced with ethical dilemmas as a result of conflicting needs and wants. These include:
- the need to give the user all the information they require and want and
- the need to withhold information that is not required, and which could overwhelm or confuse the user
- the desire to work in harmony with the people who are developing the product being documented and
- the need to be an end-user advocate which can involve suggesting product changes that may take considerable effort to implement
- the desire to work well with other writers on a team and
- the need to ensure the documentation is of the highest quality through peer reviews, which can involve constructive criticism of another writer’s work, or of your own
These conflicting needs can arise in a variety of ethical dilemmas that a technical communicator could face. Here are few examples to ponder:
You’re having trouble getting the required information about a certain feature from one of the subject matter experts (SMEs). The deadline for the release is fast approaching, and the SME is nowhere to be found. You approach the desk of the SME and see a folder on top with the title of the exact feature you need information about. However, the folder also has a large note, stating: DO NOT REMOVE. Do you borrow the folder, with the intention of giving it back as soon as you’re done with it, but knowing that the SME will notice the missing folder?
Now imagine the same scenario, but this time, you know the SME is away, and will therefore not notice the missing folder. Does this affect your decision? What if it was the same folder, but the SME accidentally left it on your desk? The SME won’t know you have the folder, but the folder still has the same note saying that the folder was not to be removed from their desk.
Another scenario: You have co-authored a user guide with another writer. Each of you have done exactly half the work. However, your manager believes you are the sole author, and praises you for writing such a fantastic document. If the other writer will never learn about this conversation, do you tell your manager you are not the sole writer? What if you knew your manager was deciding which one of you to promote? Would you then tell your manager the truth, again, assuming that the manager would never find out that you were not the sole writer? What if you had done 60% of the work? 75%? 80%? What if the other writer had previously left the company?
The point of these mental exercises is to pinpoint the exact conditions under which we believe a choice becomes immoral. By isolating the factors that influence our choices, we can learn much about the way we think and behave.
And no – I have no intention of stating what I would do in these various situations. In the book of life, the answers aren’t in the back section.
We all know (and love) our five senses: sight, hearing, taste, smell, and touch. Apparently, these senses are not enough. Science, psychology, and the arts have been on the hunt for a sixth sense since the time people knew they had senses.
Candidates for a sixth sense include:
- extra-sensory perception (ESP)
- equilibrioception – the ability to balance
As a technical person, one of the candidates that I find particularly interesting is a device called, (what else?), the SixthSense.
The SixthSense is prototype information device you can wear. It consists of a computer, a pocket projector, a mirror, and a camera. The projector projects visual information onto any surface. The user wears colored markers on their fingertips. The camera recognizes and tracks the user’s hand gestures, kind of like in the film Minority Report.
There are many cool things that you can do with this device just by using your hands to virtually “draw” various shapes:
- “draw” a magnifying glass to launch a map application
- “draw” virtual shapes onto any surface
- “draw” a frame to launch the camera
- “draw” the ‘@’ symbol to check your email
- “draw” a circle on your wrist to project a watch onto it
- use hand gestures to flick through photos you’ve taken
Most importantly, SixthSense can detect different types of physical objects and then project additional, meaningful information onto them.
Examples include projecting:
- live video news or dynamic news updates onto a newspaper
- current airline departure information onto an airline ticket.
- nutritional information and recipes onto food packages you are looking at the supermarket
- book reviews onto a book
- a person’s favourite websites onto the person’s shirt (yes, it really can do that!)
This device is a glimpse of a future world awash in meta-information. It is currently a prototype, and not freely available. However, the documentation we create is. For this, there are valuable lessons.
First – all technical communicators do have a sixth sense – the sense of information. And not just any information, but clear and meaningful information. We know, or can find out, what the user needs to know. We know how to give that information to the user. The only thing we don’t know is what what we don’t know. But we know that we don’t know what we don’t know, you know?
To find out what we don’t know, we speak with the people who do know. These are the other people involved with the product you are documenting. Particularly important are the people who are working with the users who actually use the product. These are the salesmen, product analysts, business analysts and others who have direct contact with the end users.
Second – our documentation should be as helpful as a SixthSense device. It should:
- “know” the user
- know what the user needs to know
- give them the information they need to know
- tell them how to get more or different information
- withhold information they do not need to know
Do you agree? If not, I’m not worried.
You’ll come to your senses…