Posts Tagged ‘Software Documentation’
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
Recently someone asked me what readers look for in a document. You know: are there any special “must-haves” or “sure-would-be-nice” features that make reading and using documents easier and more enjoyable? Over the years I’ve thought about this topic, researched it and have also discussed it with other writers. Here are some major themes, which apply especially to user, reference and training manuals, and other long documents:
Make information easy to find. Include all kinds of navigational aids: for starters, a table of contents, list of figures, list of tables, and an index. In some documents, you may want multiple versions of each kind. Take the index, for example. In some cases, it might make sense to have an index of features, an index of tasks, an index of commands, and so on. The upshot is this: do not bury important information. This takes some careful thought and planning.
Make information easy to understand. Know your audience. Do not make assumptions: do your homework. If there is more than one audience, make sure the document accommodates all of them, or split the document into two or more parts, and target each part to a particular set of readers. For example, you may need to account for both beginners and experienced users, and so you have to find a way to do that effectively.
Make information accurate. At the very least, your audience deserves this. Your information should also be complete and current.
Include artwork. An adequate number of screens, drawings, photos and tables will help people learn more easily and remember what they learned. Most people learn best when text and artwork complement each other.
Include tutorials and lots of examples. This is true especially if you are writing a training document. You must show your audience how to use your company’s product to perform certain tasks.
Define all terms in a glossary. Is there anything more irritating than not being able to find out the meaning of a term or its usage? Worse, that little gap in understanding can impede learning. Too many such little gaps typically give users a poor impression of a product and its manufacturer.
Balance task-oriented and reference material. Depending on the amount of material, both types might fit in one document. On the other hand, consider whether two separate documents would better serve your audience.
Streamline the document. In other words, don’t be wordy. Say something once, then cross-reference it as necessary. Organize the document tightly. To streamline, you must plan carefully and work from your outline.
So there you have it — the secret wish list of your readers. That’s what they say they want, but is that what they get when they read your documents? Elizabeth Lexleigh The Write Ideas
How do you estimate the time needed to write a document? As an example, let’s talk about the user manual, a type of document that is long, complex and typically rather tricky to finish on time and on budget.
The first step is to get team consensus on the planning and design questions (see earlier posts). Although factors vary project by project, here are some guidelines to use in calculating your estimates:
- How much do you know about the product?
- How much do you know about the subject matter?
- Who is the audience? Is there more than one audience?
- How complex is the user manual, in terms of the product, training needs, artwork, formatting, examples, and level of detail?
- How much production time is required to produce a finished, marketable document?
- How much artwork (figures, tables, illustrations, etc.) is there? Who is to create it? How will it be merged into the text?
- How many reviewers are there? How fast and thorough are they?
- Do you have established review procedures and firm timelines?
Other issues a writer needs to address include these:
- How familiar are you with the application package and other tools you will use to write and publish the document?
- Is producing the document your sole responsibility, or one of many projects you must juggle?
- How fast do you work?
- What is your approach to the project? Structured (project statement and document outline) or more random and disorganized?
Over the years I have discussed time estimates with other professional writers. On a per-page basis, their estimates have ranged widely from 1.0-1.5 hours all the way up to three days. These per-page estimates included planning and conceptual design, information gathering, an outline, a first draft, two revisions, proofreading/editing, and delivery of the document in the agreed-upon format.
So many factors can play a significant role in estimating the time required to successfully complete a document. In general, the less experience you have, the more time you should allocate. It is preferable to finish the project within your time and cost budgets than to overrun them, so allow for emergencies and unexpected delays.
Above all: no magical thinking. Be realistic. A good document (in print or online) requires a certain amount of time and money. With experience you will improve your project estimates.
When you have trouble writing about something, try to visualize it. Create a mental image of the thing, part, process, service, task or operation, and walk yourself through it. Or, take a “hands-on” tour. Make sure you thoroughly understand what you are trying to communicate to your audience.
If you continue to have trouble finding the right words, ask yourself whether you need photos, illustrations or other artwork to show the audience what you mean. The right combination of text and artwork is a very powerful teaching tool.
Another method of jogging words loose is to try to teach someone what you are writing about. Such interaction can stimulate new ideas or a new way of thinking about the subject. This is especially important when you are still mulling over how to order content and present it to your audience.
The key to handling revisions is how well you planned and structured the document, and how you handled the first draft. Now it’s time for the product and subject-matter experts to verify content.
To help your reviewers do their job when they review your document, here are some guidelines on what to check. You may want to add more items to the list, but this should get you started.
Check content for the following:
- Accuracy and completeness of information in the text
- Accuracy and completeness of any tables, figures or illustrations
- Proper use of terms, definitions, units, measures and symbols
- Logical development of subject matter in relation to the product
- Appropriate scope and depth in relation to the audience
When you send the document out for review, be sure you communicate to your reviewers what they are expected to do and the scope of their task.
Develop the “story” of your document to keep readers interested:
- Follow your outline (so you stay on subject and your writing doesn’t wander around).
- Use the principles of good writing style (some of which are presented in this blog).
- Use comparisons to communicate new or difficult-to-grasp ideas or products.
- Use “image” words to create pictures in the mind.
Many new products are based on complex technologies where parts, features, components, processes or operations are beyond the range of human perception. Each day, we are asked to understand and use things beyond the range of our own ears, eyes or hands.
To keep your document interesting, you must connect what cannnot be heard, seen or touched to what can. Use comparisons and create word images that show relation to the human scale of perception.
When you evaluate your document, ask yourself if its appearance helps your customers easily learn what they need to know, or whether it makes their job harder (or even impossible). Formatting affects how your customers perceive your product.
Bad formatting (on a printed or a web page) tends to push the reader away, while an attractive layout and legibility pull the eye through the text and graphics.
In many cases, depending on the document and its purpose, you will need to work with a good graphic artist. After all, the writer and the graphic artist each have different talents, and both make important contributions to the overall success of a document.
When you check page layout, look at each page with a critical eye, and put yourself in the reader’s shoes: Does material crowd the page? Or make generous use of “white space” (margins)? Is there enough space between lines and paragraphs? Pages should not look like a binary stream.
As a rule of thumb, call out key ideas as headings, and limit supporting paragraphs to six to eight lines. Put procedural steps in a numbered-list format. Help the reader by highlighting important points.
Select a typeface that is appropriate for your medium (print or online, for example) and your audience. Be sure the print quality is readable, so that readers will be able to easily see the typeface you choose — if you have ever tried to read very light or smudgy text, for example, you know what I mean.
Figures, tables and other artwork should be located as near as possible to the corresponding body text and, in most cases, should be numbered and captioned.
If you or your reviewers notice these (and similar) problems in the evaluation phase of a project, then it’s time to revise the “look and feel” of the document. No matter how great the content, it’s just got to have “curb appeal.” The right appearance can make all the difference in the world.
By the way, whenever you find a document that contains appealing, well-formatted pages, make a copy of a page or two and save them in a file. It won’t be long until you have a stash of handy formatting ideas ready and waiting for your next writing project.