Help for reluctant writers

Engineers and developers: use the tips on this page to write useful documents fast.

6 planning tasks

  • Identify your audience. Interview a representative from each audience group to understand how they work and what is important to them. Write a profile of a typical user. To aid realism, add a photo of your typical user.

  • Define your goals. Do you plan to produce printed manuals, online help, web site content? Do all materials need to be translated? If so, how many languages?

  • Know your subject matter experts. How do they like to work? What tools would assist them in capturing best practices and business solutions descriptions.

  • Interview subject matter experts. Place specific emphasis on best practices and business solutions using the product.

  • Identify all business solutions. Use brainstorming techniques to identify all ways real users use your product to get real work done.

  • Write topics independently from the guide itself. Assemble the topics later into a guide.

Ten questions to ask your audience

You don’t need to interview all users of your system, but concentrate on a representative sample. Include management and workers.

You’ll notice that these questions are aimed at understanding how your reader will use your system to get his or her work done. It’s more important for documentation to answer the questions real users ask than for the user guide to be organized by software features.

  • What is your primary role/job? What other roles are in your department?

    The answer to this question will reveal how much involvement each user will have with your system and help you decide on the types of documents you need: quick reference card, manuals, online help, web site, etc.

  • What do you expect from the new system?

    Managing expectations is important to the success of your implementation. The answer to this question will indicate the type of information your user needs to understand to use the system and where misunderstandings are bound to arise. Use this knowledge to organize materials based on user needs.

  • When you come in on Monday morning, what are your goals for the day, the week?

    The answer to this question will help you organize topics into daily and weekly tasks.

  • What problems do you encounter daily that keep you from getting your job done? What kinds of exceptions do you deal with?

    This question is another way to identify user-oriented topics.

  • What reports do you produce and refer to?

    This information will help you to decide where to document report preparation and access.

  • When you have too much to get done, how do you prioritize your time?

    The answer to this question will help you organize material so that the most important information is easily accessible.

  • How do you interface with other departments? What information do you give them? What information do they need from you?

    Use this knowledge to help you decide on topics to cover.

  • What deadlines do you regularly meet?

    This information may provide practical examples you can use in your documentation.

  • What issues and problems do your customers call you about?

    This knowledge will help you better understand the pressures on your readers and give you ideas for topics to include.

  • What system-related regulatory requirements do you meet?

    This information will help you ensure that you cover all important topics.

Once you have a clear understanding of how your users work now, you will be able to write procedures for the new system and identify best practices that will make sense to them.

4 steps to prepare for the writing task

  • Assemble source materials.

  • Consult style guide.

    If you don’t have an inhouse style guide, use the current version of “Microsoft’s Manual of Style for Technical Publications.”

  • Set up your writing software.

  • Block out time to work without interruptions.

5 ways to organize for quick reference

Don’t expect users to read the guide you’re writing! Do expect them to use it to find out how to get things done with your system and how to solve any problems they encounter.

Here are things you can do to make your documents easier to use.

  • Organize chapters and topics within chapters based on what your users need to do to meet their work-related goals.

  • Organize chapters in priority order with the highest-priority tasks first.

  • Put installation information and theory-of-operations information in appendices.

    Users don’t really care how your system works! They care about how to use it to get their jobs done.

  • Write a title for each topic that answers the question, “How does this topic benefit the reader?”

  • If your user guide contains more than 50 pages, include an index.

    Most people are trained, if they can’t find what they’re looking for by paging through a document, to look in the back for an index. This is one of the most important features you can provide.

10 steps to write a procedure

Writing successful procedures is an more an art than a science. People don’t like to read. Use these points to create useful procedures.

  • Pick a title that reflects the business solution achieved by the procedure.

  • Write an introductory sentence that tells the reader why he or she should read this procedure.

    This is the benefit for the user. Much of documentation users struggle to use suffers from the lack of this information. Remember, your reader most likely will not understand the terminology used by your system. Just like a good novel has a hook that engages the reader, user manuals need to clearly state explain why a given feature matters to the reader.

  • Identify any prerequisites for the task: knowledge, tools, other completed procedures the user needs to successfully complete this procedure.

    Don’t bury the requirement for a Phillips screwdriver in the steps themselves. Let the reader know up front what tools they need.

  • Start from scratch. Don’t assume the user is as knowledgeable about the procedure as you are. If the reader needs to turn the power on first, show them, using a diagram, where the on switch is.

  • Write steps in order, including only one action per step. Start the step with the command form of the verb, for example, “Tap Send.”

  • After each step describe what happens when the step is complete.

    Do not put this step result information in the next step. Each step should start with an action, not a result.

  • Include relevant illustrations and examples. Do not include screen captures that provide no relevant information.

    Use callouts to identify what you’re talking about and use terminology consistently.

    Don’t refer to something one way in the illustration and another way in the text.

  • Put text about a given illustration below the illustration.

    This enables readers to scan the procedure using the pictures, stopping only when they see something of interest.

  • If more than nine steps are required, break the procedure into two sub-procedures.

    Readers tire easily. A procedure with 15-20 or more steps looks hard.

  • At the end of the procedure, describe the result of the procedure and provide any links to further information.

10 steps to self-edit a topic

Ideally, every author should have an editor. An extra pair of educated eyes can make the difference between an excellent document and an embarrassment. But, most technical writers don’t have the luxury of working with an editor. Pay attention to these suggestions as you self-edit your topics.

  • Never edit your own work without taking a long break, preferably sleeping on it for at least one night first.

  • Spell-check the topic.

  • Print out the topic and mark it up using a red pen or other color that stands out clearly.

  • Verify the topic with the product.

  • Read the topic looking for missing words, incorrect grammar and punctuation.

  • Read the topic paying attention to formatting. Does each illustration have a caption? Are graphics placed correctly?

  • Turn the page upside down and look for things that stand out.

  • Make all the changes you found, marking each change as made on the editorial copy.

  • Spell-check again; print out the top again and double-check your changes.

  • If you are able, make a list of the things you corrected during the edit. Use this list to help you with the next topic.

Copyright 2010 The Atkins Group All Rights Reserved