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

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


PREVIEW

                                                                          

Not a subscriber?

Start A Free Trial


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