Posts Tagged ‘Technical Writing’
Around 1980, some companies and organizations, notably the aerospace industry and the branches of the U.S. military, began to re-think how they presented technical information. Their products were complex, and their maintenance, troubleshooting and product-support requirements were stringent and time-consuming.
They knew they needed to improve performance, reduce errors, and shorten learning timelines. But how?
As it happened, they looked at emerging computer technologies and wondered if moving from paper to an electronic format would improve results. Among their questions:
- Would users find it easier to learn and use the material?
- Would they reduce errors and improve performance?
- Could they integrate documentation with other systems?
- Could they save money?
Tests with interactive electronic formats showed positive results and so, encouraged, the companies and the military forged ahead into the world of Interactive Electronic Technical Manuals (IETM).
Since that time, we have seen IETM systems develop a variety of features, with most using one or more of the following:
Linear Structure. This sort of electronic document is based on the structure and layout of a printed book and uses navigational aids, such as a table of contents and a list of figures, that hyperlink into the content. A PDF file is a good example.
Nonlinear Structure. These online documents are organized around the logic of the product or task, for example, instead of following a linear book-type structure. However, the concept of a static page remains. As you would expect, there are lots of hyperlinks and other navigational aids. This type of document is often authored in a markup language.
Dynamic Data. These online documents are very nonlinear in structure. Content and pages are dynamic, drawing much of their data from relational databases and data dictionaries. Background programming automatically updates the dynamic data when the databases and dictionaries are updated. Hyperlinking in these documents is typically very complex and is, therefore, usually handled by programming. Content may also be context-specific and user-specific.
Integrated with Expert Systems. As companies build databases of heuristics and expert feedback, these can be integrated with the IETM system to improve the user experience and results. This information can be dynamically mapped into documents in all sorts of ways. For example, feedback by expert troubleshooters about errors and how to resolve them is sought after by companies across the product and process spectrum.
New Frontier—Multiple Devices. Many companies are now changing the way they and their customers think about IETM. From design concept to reality, they are experimenting with unleashing product support through all sorts of channels, for example: Mobile devices such as tablets and phones, YouTube, Facebook, Twitter, websites, CDs, PDF, print, wikis, and blogs.
The new frontier of IETM seems to call for a “basket” of delivery platforms, each carefully selected for a certain type of content.
And no matter the platform, content rules. As ever.
Content must be organized in a way that suits the product, the audience, and its intended use. Content must be consistent across multiple platforms, well structured, properly modularized, cross-referenced and completely accessible by a full range of search and navigational features.
IETMs and their spin-offs present design, writing and production challenges, but produce a better user experience and greater performance improvements over stand-alone paper documents.
For more on creating an interactive user experience, see my recent post Let Your Customers Tweet in Your Documents.
Now it’s your turn: Does your company use IETMs? On which delivery platforms? How would you describe your experience implementing IETMs? Do you think the results are worth it? Please share your thoughts and questions about IETMs in comments. Elizabeth Lexleigh LexPower The Write Ideas
If you started to think about your company’s publications as behaviors instead of things, would such a shift in perspective change the resulting documents? Would your customers respond to your message in a different way?
Consider the publications that you and others in your company create—they probably run the gamut, from sales and marketing literature to online pages to proposals to technical documentation and maybe even to interactive multimedia presentations and video scripts.
Like most writers, you work with others to establish the requirements for each publication and to generate and refine its specifications. You create an outline that captures the topics, features and procedures to be included in each document and organize that content in a way that satisfies the project specifications.
Such an approach is based on seeing the document as a thing. And, while it may be necessary, at least in part, is it sufficient? Does it really satisfy your customers’ needs? Does it let you wring every last drop of value out of what you spend on trying to connect with your customers?
What if you viewed a publication as a set of behaviors, instead of just a thing?
For starters, this might mean that your project requirements stated how your company’s customers would interact with the publication—and any associated product. After all, why do your customers read your stuff? What do they expect to get out of it?
If you thought about customer behaviors—for example, how they use the publication, the ways in which they need to access the document, how they find topics, how they use the information, what other resources they might need, how they might use the document as a focal point for customer-to-customer and customer-to-company interaction—would those considerations change your document specifications? Would the specs begin to reflect a mindset that took user experience into account?
If you viewed each publication as describing, prescribing and integrating a dynamic set of behaviors among your customers, your products and your company, how would that change the types of documents you create?
Would you enhance your publication model to include various scenarios and anticipated interactions that played to customer needs and experiences?
Begin to think about your company’s publications as behaviors instead of things, and I’ll bet your documents become more interactive, more dynamic, more user-friendly and more attuned to your customers.
Now let’s talk: What is your opinion? If you create publications, what is your approach? As a customer, how do you respond to companies’ offline and online publications: What do you like about them? What don’t you like? You can leave your comment at the top of this post. Elizabeth Lexleigh LexPower The Write Ideas
This timeline caught my eye. It encapsulates the concepts of emergence, process, change and transformation so well; it’s colorful, witty; and I just liked the delightful style.
You could say this graphic offers us one view of human evolution. But on a larger scale, the drawing also conveys the overarching concept of transformation: things change, don’t they? They can adapt, mutate, flourish and take off in one or more directions. They can also stultify, remain static, wither and perish. A single, accidental mutation in one organism—or even the organism’s extinction—can give rise to a profusion of new, dissimilar life forms.
One thing for sure, though: Nothing stands still in time, at least not for very long. Time inexorably modifies, erases, transfigures, changes, enhances, diminishes, grows, dies, creates and destroys everything. Time is motion. We all obey time, and this charming timeline about us and everything else gets that point across beautifully.
And how about this clock?
The clock shows how the use of graphical elements like repetition and shadings of color can communicate change, transformation and adaptation.
Depending on the context, the clock graphic could represent the literal passage of time, nothing more. But drop the image into the history of an individual or a company, or a description of a manufacturing process, or an account of the evolution of an idea, for example, and the image takes on new meanings.
Beyond that, a skilled artist could re-work this or any other timeline graphic in all sorts of ways. The artist, who lives in a time stream, as we all do, is also one of time’s agents and, as such, behaves as a sort of time proxy and serves as an entity who has the power to alter things—in this case, a graphic image. In his drawings, M. C. Escher joyfully plays with just such self-referential notions.
The next timeline is a tongue-in-cheek image that purports to show how humans evolved from a more primitive life form—from ape to human in this example. As any biologist knows, however, such a representation is technically incorrect. Rather, it seems that humans and apes share a common ancestor, which means we are not the descendants of apes, but more like their kissin’ kin.
The previous image is like the first two images in that on a larger scale it says something about the essence of life, which includes concepts of emergence, adaptation and transformation. On a smaller, more specific scale the image says: If you are here reading this, then you can thank a very long line of ancestors (a line so long that it stretches, unbroken, beyond an ape-like ancestor, all the way back to single-celled bacteria so primitive they didn’t even have a nucleus).
You may have seen an adaptation of the previous image, one in which the final figure was a pair of high heels, representing woman. I don’t recall the context in which that image appeared, but the high heels completely changed the meaning by implying that the most advanced form of life was the human female. Or maybe the sort of female who wears heels.
The next and final timeline in this post shows another view of the transformation of human life, from extinct ancestral hominin forms to related hominids to … us–Homo sapiens, at the top of the left branch. Although incomplete, the evolutionary tree in the graphic shows a distinct bifurcation, with a right branch leading to the genus Pan (chimpanzees), our closest primate relatives.
This image is much more detailed than the previous one, and more scientifically accurate as well. It includes a timeline (on the left side) that shows a scale of millions of years. The image makes clear that as life flows along in time, it changes in myriad and unpredictable ways, and it is only after the fact that we can map out the transformations on a timeline and assign values to them.
Together, these four images show just a few of the many ways you can use timelines to get across concepts about emergence, change, adaptation and transformation. Whether you are looking at life in general, or some aspect of it, timelines are useful tools to communicate your ideas.
For more about timelines, you might like to read the following posts in my blog:
If you would like to learn more about the timelines of your own personal ancestry, visit The Genographic Project.
Now it’s your turn: Do you use timelines in your work? What is your subject matter? Do you think timelines are useful in communicating with your audience? Please share your thoughts about timelines. Elizabeth Lexleigh LexPower The Write Ideas
Does your company’s documentation provide excellent customer service, cut down on the costs of customer support (those call-center calls are not cheap) and help bring in qualified leads?
Is your documentation just a cost center or a smart investment that helps drive revenues?
Does your documentation help you win repeat business and attract new customers?
Really great product and services documentation can (and should) be an important part of your company’s business strategy. If you’ve always thought of documentation as just something you had to do, because every other company does, well, you’re missing out on a powerful tool that can help you lower costs and increase revenue.
What Makes Quality Documentation?
While quality documentation has many characteristics, the net-net result is that it provides a superior experience when your prospects and customers interact with your products and services. That, in turn, happens when the documentation makes it easy (and maybe even interesting and perhaps—gasp!—fun) for a prospect or a customer to find information they want, to learn what they need to know, or to solve a problem.
Put another way, it’s all about developing productive and valuable relationships with your audiences. And documentation is at the heart of it all.
Here are two key characteristics that are often overlooked, and that I think are essential if you want to build great documentation that will help you outmaneuver your competitors.
List of User Tasks and Links to Solutions
A key characteristic of excellent product and services documentation is the list of user tasks and links to the solutions. Even if you have parts and pieces of this elsewhere in your documentation, you need to have one section or module that lists every task and its links. Your listing should present tasks from a customer’s perspective, for example:
I want to do X…
How do I …?
When you create a task list, it is critically important that you use terms and phrases geared to your target audiences, which means you have to know who your audiences are and how they think. So be prepared to don your research hat.
How many times have you tried to find something (in print or online) and failed, only to discover that the documentation did in fact contain the topic you were looking for, but the index entry or other references to that topic required you to use one specific search term or phrase? And which one? Oh, it’s guess-a-lot time? Isn’t that frustrating? Help make your corner of the world a little happier by using a variety of terms and phrases in indexes, and build your search engines so they display “close but not quite” matches. Help your users find those tasks.
Your goal is to create a superior experience that helps build a positive relationship between your company and its customers.
A Customer-centric Perspective
The second key characteristic of outstanding documentation is that menus, options and features are presented and explained from a customer-centric perspective.
After all, your customers will look at your product and its parts and ask: Why would I use this? To do what?
When you explain menus, options and features, be sure to:
- Focus on real-world applications.
- Provide links to detailed how-tos.
To create documentation that is all about the customer requires thought, research and effort. This is much more difficult than merely churning out material that is product-centric or developer-centric, and is probably one reason why too many companies still produce perfunctory and ineffective documentation that is, quite frankly, not all that useful to the end user.
Great Documentation Is an Asset
Whether your company is a high-tech geek enterprise or entirely non-technical, your business needs great documentation to win in the marketplace.
It’s part of paying attention to your customer, as well as leveraging what can be an important sales and revenue-generating tool.
So, how is your documentation doing? Is it working for you?
Please share your thoughts by leaving a comment. Elizabeth Lexleigh LexPower The Write Ideas
Do you think it is ever appropriate to use the word you in technical documents?
At one company, where I was working as a contract freelance writer on a technical-writing project, the company’s lead technical writer decreed that no one was to use the word you in any technical document. Ever. Under any circumstances. For any reason whatsoever. He considered it too unscientific and non-technical.
For example, we were supposed to write: After the user enters the data, he or she should check the form before clicking the Submit button, instead of: After you enter the data, check the form before clicking the Submit button.
The first example sentence illustrates technical or scientific style, which is impersonal and presents content in a way that largely avoids personal pronouns (no you allowed, for example) and does not directly address the reader. This style favors the passive voice (which also helps avoid those pesky pronouns) and promotes nominalization (a process in which verbs are turned, sometimes illegally and indecorously, into nouns).
If you have ever read texts overflowing with words like optimization, monetization and the like—nouns created from verbs by the writer—then you are familiar with the technique of nominalization.
Technical style is frequently used in processes and procedures, which place the emphasis on the sequence of the action rather than on giving directions to the reader. In other words, a step is described, not written as an order or directive. Thus, the user is addressed indirectly and impersonally in the third person as he, she, one, the operator, the technician, the user, and so on.
All of that is supposed to sound more technical and scientific—as well as more objective and authoritative, in the opinion of some.
The second example sentence shows conversational style, in which you write to readers as though you are speaking to them. This style approves of using personal pronouns (you, for example) as well as the judicious use of contractions (don’t instead of do not).
As a bonus, conversational style encourages the use of the active voice, which adds conviction and liveliness to writing, and is almost always more concise than the passive voice. Readers find “action verbs” appealing, because such verbs are direct and show motion.
Using a conversational tone in technical communication can be quite effective and very engaging, as long as you don’t overdo it. Specifically, “not overdoing it” means to refrain from writing in a colloquial or chatty manner, using slang, and attempting to be humorous.
Conversational style is often used when writing directions, because you are telling the reader how to complete an action. Thus, the writer addresses the reader as you. For example: You must not enter a space between the numbers in this field. When writers use the command form of a verb, however, the you is not explicitly stated: Use only clean tools.
Striking a Balance
So, to you or not to you, that is the question.
In my opinion, it is preferable first to define and understand your audience, define the purpose of the document and understand your company’s communications objectives for the document, and then decide on a case-by-case basis whether to use the word you (and by implication, a more conversational style).
Given those parameters, I’m pretty certain you won’t be able to decide to “always” or “never” use the word you. It’s more likely you’ll find it necessary to strike a balance regarding its usage.
Even if your company has a style guide that addresses this issue, I’ll bet there will be times when its rules about when to use the word you will need some tweaking. What matters, after all, is how well you communicate with your audience, your customers, and if you have to bend a rule or make an occasional exception, then so be it. (Just be sure to discuss it with your manager first, of course.)
What do you think? Has the issue of using the word you in technical documents ever become a bone of contention in your company? Elizabeth Lexleigh LexPower The Write Ideas