Posts Tagged ‘Software Documentation’
Conversational Style in Communicating Technical Information - Image: healingdream / FreeDigitalPhotos.net
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.
Technical Style
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.
Conversational Style
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
Project Time Estimates
Posted on: October 12, 2009
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.
LexPower 