• Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint
Share this Page URL

Part 2: Easy to understand

Part 2: Easy to understand

Whether technical information is easy to understand depends mainly on how it is presented at the level of small structures such as words and sentences. It can also involve larger structures such as examples and scenarios.


Chapter 5 Clarity


Focus on the meaning


Avoid ambiguity


        Use words with a clear meaning


        Avoid vague referents


        Place modifiers appropriately


        Avoid long strings of nouns


        Write positively


        Make the syntax of sentences clear


Keep elements short


        Remove roundabout expressions and needless repetition


        Choose direct words


        Keep lists short


Write cohesively


Present similar topics in a similar way


        Use lists appropriately


        Segment information into tables


Use technical terms only if they are necessary and appropriate


        Decide whether to use a term


        Use terms consistently


Define each term that is new to the intended audience


In sum


Chapter 6 Concreteness


Choose examples that are appropriate for the audience and subject


        Consider the level and needs of users


        Use examples appropriately in conceptual, task, and reference information


Use focused, realistic, accurate, up-to-date examples


Make examples easy to find


        Use visual cues to indicate where examples are


        Make examples part of the user interface


        Make clear where examples start and stop


Make code examples easy to adapt


Use scenarios to illustrate tasks and to provide overviews


Set the context for examples and scenarios


Relate unfamiliar information to familiar information


Use general language appropriately


In sum


Chapter 7 Style


Use correct grammar


        Check for sentence fragments


        Correct pronoun problems


        Correct dangling modifiers


Use correct and consistent spelling


Use consistent and appropriate punctuation


Write with the appropriate tone


Use an active style


        Use active voice


        Use the present tense


Use the appropriate mood


Follow template designs and use boilerplate text


        Create and reuse templates


        Use boilerplate text to ensure inclusion of necessary information


Create and follow style guidelines


        Provide practical and consistent highlighting


        Present list items consistently


        Use unbiased language


In sum



Not a subscriber?

Start A Free Trial

  • Creative Edge
  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint