Clarity in Documentation

Novell® TECHPUB's Book
Review Session: Clarity
Radhika PC
Technical Writer
ISM BU, Novell

© Novell, Inc. All rights reserved.2
Clarity is the property of being clear or transparent.
Clarity can refer to one's ability to clearly visualize an object or
concept, as in thought, understanding, and the "mind's eye", as
well as the traditional notion of visual perception, that is, with the
actual eyes.
-Wikipedia
...Easy Reading is Damn Hard Writing..!!

Easy Reading is Damn Hard Writing..!!
Clear information is the result of Rewriting--Replacing,
Adding, and Deleting parts to achieve clarity
Clarity-related issues can be resolved at the level of
Words and Sentences
Clarity provides the rationale for many decisions about
Style and Visual Effectiveness
Clear Information requires a strong focus on what users
need to know and when they need to know

Guidelines
Focus on the Meaning
Avoid Ambiguity
Keep Elements Short
Write Cohesively
Present Similar Information in a Similar Way
Use Technical Terms Only if Necessary and Appropriate
Define Each New Term to the Intended Audience

Focus on the Meaning....
Original:
A major company maintains a large personnel database that is basically
makes use of for many kinds of employee-related applications such as
payroll and benefits. The company now has some plans to extend the
database significantly to include current photographs of employees and
use the photographs as the basis for a very modern security system. The
system is specifically designed to protect secure areas of the company's
building from access by any people who really do not have authorization to
be there.

A major company maintains a large personnel database that is
basically makes use of for many kinds of employee-related
applications such as payroll and benefits. The company now has
some plans to extend the database significantly to include current
photographs of employees and use the photographs as the basis
for a very modern security system. The system is specifically
designed to protect secure areas of the company's building from
access by any people who really do not have authorization to be
there.

Revision:
A company plans to extend its database to include employee
photographs. The company wants to use the photographs in a
security system that will protect certain areas of the building from
unauthorized access.

Eliminate:
Imprecise Words: now has plans to, makes use of, kinds of
Intensifying Words: basically, significantly, very, specifically, really, some, any
Unnecessary Modifiers: major, large, many, current, modern
Long sentences: company's building from access by any people who really do not
have authorization to be there
Conclusion:
Make every word count. Eliminate words that do not
contribute to the meaning

Avoid Ambiguity
(Have mercy on translators and nonnative speakers)
Use words with a clear meaning
Avoid vague referents
Place modifiers appropriately
Avoid long strings of words
Write positively
Make the syntax of sentences clear

Use Words with a Clear Meaning....
Original:
The timer function functions to stop certain actions.
Revision:
The time function stops certain actions.
Original:
The team documents design changes.
Revision:
The members of the team document the changes in the design
Conclusion:
Use words that have clear meaning. Look for the ways that words might be
misunderstood, particularly by nonnative speakers of English.

Avoid Vague Referents....
Original:
DbInfo is a virtual database that you can create from the target file system. It consists of a set
of statements that provide input to the projection utility.
Revision:
DbInfo is a virtual database that you can create from the target file system. The database
consists of a set of statements that provide input to the projection utility.
Original:
You can have multiple catalogs for a single source;however, each can access only one.
Revision:
You can have multiple catalogs for a single source;however, each catalog can access only
Conclusion:
Check that the antecedents for the pronouns that you use are clear. Aware of the
common pronoun errors as you write or edit.

Place Modifiers Appropriately....
Original:
Click the configuration server to which you want to link the list manager servers in the Configure
Server Name field.
Revision:
in the Configure Server Name field, click the name of the configuration server to which you
want to link the list manager servers.
Original:
Programs that produce errors consistently require regular maintenance.
Revision:
Programs that consistently produce errors require regular maintenance.
Programs that produce consistent errors require regular maintenance.
If a program produces errors, it consistently requires regular maintenance.
Conclusion:
Make sure that modifiers are in the correct position relative to what they need to
modify.

Avoid Long Strings of Nouns....
Original:
Use the input message destination transaction code as shown in the example.
Revision:
Use the transaction code for the destination of an input message as shown in the example.
Original:
The sample dynamic plan selection routine is in the Samples folder.
Revision:
The sample routine for dynamically selecting a plan is in the Samples folder.
Conclusion:
Avoid creating noun strings with nouns that should be verbs. Eg: error recovery (to
recover from errors), Performance control (to control the performance)
Rewrite the strings that have more than two nouns. While doing it, start with the
noun or pair of nouns at the end of the string.

Write Positively....
Original:
Do not install InfoConnect until you check that your computer does not have these conflicting
programs.
Revision:
Before you install InfoConnect, check your computer for these conflicting programs.
Original:
Transitions cannot occur between states that are inherited from different classes or between
local and inherited states.
Revision:
Transitions can occur between states that are inherited from the same class or between lstates
Conclusion:
Some negatives are necessary and useful ( warning, restrictions)

Make the Syntax of Sentences Clear....
Original:
Each illustration accurately depicts an object, concept, or function.
Revision:
Each illustration accurately depicts an object, a concept, or a function.
Original:
Unique bit pattern that is defined in code page.
Revision:
A unique bit pattern that is defined in code page.

Keep Elements Short
Remove Roundabout Expressions and Needless Repetition
Choose Direct Words
Keep Lists Short

Remove Roundabout Expressions and Needless
Repetition.....
Original:
You can display a visible grid on forms to help you place components.
Revision:
You can display a grid on forms to help you place components.
Original:
Given the fact that you have created an object, it can operate in a manner independent of other
objects based on the same class.
Revision:
After you create an object, it can operate independently of other objects of the same class

Choose Direct Words....
Original:
Modifications to a shared property apply universally to objects on the objects list.
Revision:
Changes to a shared property apply to all objects on the object list.
Conclusion:
Choose direct words as appropriate for your audience.
Avoid using phrasal verbs because many such verbs are not defined in the
dictionary.

Keep Lists Short....
-Seven items maximum for online information.
-Nine items maximum for printed information.

Present Similar Information in a
Similar Way
Use lists appropriately
Segment information into tables

Use Lists Appropriately....
-Use an ordered list for information where the sequence or priority is
important.
-Use simple list for items of similar importance. Keep the list items
parallel.

Use Technical Terms only if They are
Necessary and Appropriate
Decide whether to use a term
Use terms consistently
Avoid Jargons

Decide whether to Use a Term..
-If a widely used and accepted term does exist, use it. Don not coin a new term.
-If you intend to use a term only once or twice, use descriptive phrase instead.
-Don not create acronym unless you will use it often.

Use Terms Consistently..
Original:
The invoice class contains the LineItem class. The AddLineItem method of the
invoice class accepts only objects of the LineItem type.
Revision:
The invoice class contains the LineItem class. The AddLineItem method of the
invoice class accepts only objects of the LineItem class.

Define Each Term that is New to the
Intended Audience..
-Define Acronyms and Abbreviations
-Definitions are easy to understand

If the writer does not sweat, the reader will.....
-Mark Twain

Unpublished Work of Novell, Inc. All Rights Reserved.
This work is an unpublished work and contains confidential, proprietary, and trade secret information of Novell, Inc.
Access to this work is restricted to Novell employees who have a need to know to perform tasks within the scope
of their assignments. No part of this work may be practiced, performed, copied, distributed, revised, modified,
translated, abridged, condensed, expanded, collected, or adapted without the prior written consent of Novell, Inc.
Any use or exploitation of this work without authorization could subject the perpetrator to criminal and civil liability.
General Disclaimer
This document is not to be construed as a promise by any participating company to develop, deliver, or market a
product. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in
making purchasing decisions. Novell, Inc. makes no representations or warranties with respect to the contents
of this document, and specifically disclaims any express or implied warranties of merchantability or fitness for any
particular purpose. The development, release, and timing of features or functionality described for Novell products
remains at the sole discretion of Novell. Further, Novell, Inc. reserves the right to revise this document and to
make changes to its content, at any time, without obligation to notify any person or entity of such revisions or
changes. All Novell marks referenced in this presentation are trademarks or registered trademarks of Novell, Inc.
in the United States and other countries. All third-party trademarks are the property of their respective owners.

Clarity in Documentation

Recommandé

Recommandé

Contenu connexe

Similaire à Clarity in Documentation

Similaire à Clarity in Documentation (20)

Plus de Radhika Puthiyetath

Plus de Radhika Puthiyetath (11)

Dernier

Dernier (20)

Clarity in Documentation