Posts Tagged ‘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.
Planning a writing project establishes the framework for writing the document and sets the stage for all subsequent work: conceptual design, gathering information, writing, and evaluation.
The decisions you make in the planning phase will be used throughout the project to guide your work and, eventually, to help judge the results. Planning allows you to measure whether the document meets project requirements.
After your meetings with the project team, write a memo containing the planning questions and answers. Distribute copies to all members of the team with a request for feedback. It is imperative for the success of the project that you get buy-in from everyone. No going forward with the project until all team members agree on each point!
If there are any subsequent changes to any of the planning decisions, send a written copy of the changes to everyone. Be prepared to negotiate your way to a final agreement with all team members.
If you are the entire team at your company, then ask yourself the planning questions, make the decisions, and write down your answers. Formalize the process to clarify your thinking and establish a benchmark for judging the outcome of your work. Oh — be sure to run the memo by your boss, so there are no unexpected surprises late in the project.
Planning is the first step in maintaining control of your work. It is absolutely indispensable.
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.
Bad writing can ruin any type of document, no matter how good the planning, organization of the document, or content. It is difficult to write words that work.
Successful written communication depends on how well something is said. For example, a writer can help and support the users of your company’s products, or stop them in their tracks. One remedy for bad writing is to insist on finding a professional business and technical writer for your projects, and to be sure that the writer you select knows or is able to learn the subject matter.
When evaluating your own or someone else’s writing, here are a few things that indicate a problem:
Readers cannot understand what the writer is trying to say, due to deficiencies in language usage. Bad grammar, incorrect spelling, and misuse of punctuation are common culprits.
Readers are confused, because the writer refers to one thing in many different ways. Remember to be consistent in use of terms, references, and so on.
Readers get tangled in long, convoluted sentences and overcomplicated expressions. Analyze your language for wordiness, clichés, and mangled syntax. Get to the point. Keep your paragraphs, sentences and words short and simple.
Readers cannot understand made-up verbs and phrases. You cannot just turn nouns into verbs, or tack “-ize” on to perfectly nice nouns and verbs. Check your dictionary. Also, avoid gobbledygook and excessive use of jargon. Use language to communicate, not hide.
When you spot these and similar issues in a document, resist the temptation to decide they don’t matter all that much. Do not foist a badly written document on your audience. They and your company deserve better.
Do the right thing, and revise.