clarity in documentation

Novell® TECHPUB's Book Review Session: Clarity

Radhika PCTechnical WriterISM 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 clarityClarity-related issues can be resolved at the level of Words and SentencesClarity provides the rationale for many decisions about Style and Visual EffectivenessClear 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 DisclaimerThis 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

Engineering