Technical Writing Principles and Techniques

8/6/2019 Technical Writing Principles and Techniques

1/21

Lecture One: Principles of TechnicalWriting

This lecture deals with the principles on which all technical writing is based.

Although most people have a general idea of technical writing, the common

perception is based on the idea that such writing is an uninteresting collection

of technical details and dry facts. Unfortunately, this impression is reinforced

by the fact that many peoples contact with technical writing is the manual

that accompanies a household appliance which quite often is not well

written.

The fact is that technical writing is based on much more than technical

terminology or curt instructions. Good technical writing is based on insight

into the needs of the person reading the documentation. To produce a good

piece of technical writing you have to understand how people use technical

writing, and what the readers expectations are.

A good technical writer possesses strategies for gathering information about a

product and for figuring out what the user must know to operate it.

You do not have to have a particular technical background to write Userdocumentation. Some of the best user documentation is written by people

in the humanities and social sciences, people who understand how to

communicate with naive users. What you do need is an understanding of

How people use technical documentation.

How to gather information about a product.

How to organize technical information into a logical outline.

How to translate that outline into a full-fledged manual.


2/21

YEDA School for Technical Communications

Principles of Technical Writing

1-2

How Manuals are Used

The key to understanding how to write a manual is to understand how the

manual will actually be used. To better understand this, think back tohow you use manuals and complete the following exercise.

Exercise 1: Understanding User DocumentationDescribe how you learn to use a new appliance or software program. What

role does the User manual play? How does your use of the user manual

change as you become more familiar with the product?

Exercise 1: CommentaryThe majority of people respond to this exercise by stating that they first try

out a few features of the new product independently of the manual i.e., theytry to figure out its use without reading. The use of documentation differs, of

course, according to background, previous experience using similar kinds of

documentation, familiarity with the system or type of system, etc. However,

one thing is fairly common to all types of users a certain reluctance to read

technical manuals. I think this is actually true for more than technical things:

most kids learning to ride a bicycle will immediately make attempts to ride it

without bothering to listen to instructions and explanations on how its done.

This attitude carries over into adult life as well: it is difficult (and somewhat

boring) to read instructions, understand them, and remember them long

enough to successfully implement them.

The bottom line is this: people dont like to read technical manuals andthey will generally use the documentation only when forced to. Thus,when a difficult situation arises in which the user cannot intuitively figure out

how to proceed, the manual is there to provide assistance.

Exercise 2: RamificationsHow does the way of using documentation affect the way we write it? What

are the major characteristics that documentation should have?

Exercise 2: CommentarySince the basic principle is that people normally use manuals only when they

need to solve a problem, we can deduce the following ramifications for the

way manuals should be written:


3/21



1-3

The writing should be clear and easy to understand since the user doesnot have the luxury or patience to concentrate on the manual rather,

he is concentrating on the system itself and its application.

When confronted with a problem, the user needs to find the appropriateinformation quickly therefore the manual needs to be organized in a

way that promotes this.

The manual should be as short, and to the point, as possible withoutdetracting from its explanatory power.

Later in this lecture we will explore how these characteristics are applied to

good user documentation.

What makes writing "Technical Writing"?

Technical writing is writing about technology. Its purpose is to explain the

technology and to instruct others in its use. The length and complexity of the

writing is usually related to the complexity of the product for which it is

written. For low-tech products (mechanical or electrical systems with a

minimum of controls), the technical documentation is generally short and

simple. For hi-tech products, those that are controlled by microprocessors and

offer many controls, the documentation is often hundreds of pages and

contains many explanations and operating procedures.

Beginning students in technical writing often think that technical writing hasto sound technical, as if that is its defining characteristic. They often ask if

their writing is "technical enough". Unfortunately, this is a very confused way

of defining technical writing and an even more confused way of evaluating it.

Every type of writing has its own criteria for evaluation, depending on what

the writing is supposed to accomplish. For example, a poem should provoke

an attitude or emotion. Asking whether the poem sounds "poetic" enough, or

whether it has rhyming words, is nonsense. Technical writing is judged by its

own special criteria. Sounding "technical" has nothing to do with it.


4/21



1-4

Definition of Technical Writing

The following definition provides us with criteria for evaluating technical

writing:

Technical WritingInstructions and/or descriptive material relating to a particularproduct to facilitate its use.

Let's analyze the definition. Its major advantage is that it tells us what

technical writing is supposed to do, to "facilitate the use of a product". By

facilitate I mean to "make easier", to "help make more efficient" and in some

cases to "make possible". This is the bottom line of all technical writing: doesthe writing help the user operate the product more successfully? Does the

writing relate to a product at all? In evaluating technical writing, we are not

concerned with whether there are technical terms, whether there is a

formalistic approach, whether the writing is lengthy or laconic; we are

concerned with only one thing: does the writing make it easier for the user to

use the product?

Exercise 3: Technical Writing as a Form of WritingCompare the following examples of writing; which ones seem to you to

qualify as technical writing according to our definition? Why?

Example 1

To get help on a command:

1 Press Shift+F1; the pointer changes to a question mark.

2 Choose the command from the menu; Word displays information about the command.

Example 2

"Each meta-mathematical statement is represented by a unique formula within arithmetic;

and the relations of logical dependence between meta-mathematical statements are fully

reflected in the numerical relations of dependence between their corresponding arithmetical

formulas. Once again mapping facilitates an inquiry into structure. The exploration of

meta-mathematical questions can be pursued by investigating the arithmetical properties

and relations of certain integers."


5/21



1-5

Example 3

Connecting the Printer to a Computer

1 Insert the 36-pin plug into the parallel interface connector on the right back of the

printer.

2 Snap the 2 wire clips onto the plug to make a secure connection.

3 Connect the other end of the cable to a computer.

4 First turn on the printer's power, then the computer's power.

Example 4

An implementation of 10th order LPC analysis has been developed for the TMS320 signal

processor. The TMS320 signal processor uses a sampling rate of 8 kHz, a frame size of 30

ms, and a frame period of 20 ms. This combination of frame size and period results in a

frame overlap of 33 percent, where each sample contributes to an average of 1 - 1/2 frames.

The DSP implementation described here uses a frame overlap of 67 percent, and this

requires three frames of computation to be completed on each sample. However, anincrease in recognition error rate accompanies the reduction in computation obtained by a

reduction in frame overlap as shown by numerical simulations. In the TMS320 signal

processor implementation, the same circuit also performs pattern matching for connected-

word recognition.

Example 5

Let us now consider a further objection, also on grounds of triviality. It might be said that

the universal proposition which is generated, in the way described above, by any singular

descriptive judgement is merely a matter of the meaning of the descriptive term contained

in the judgement; that it cannot be a matter of substance. If I say that X is red, I am

committed to holding that anything which is like X in a certain respect is red too. In using

the descriptive term 'red' I must be employing some universal rue; but, it might be objected

this rule is only that which gives the meaning of 'red'; it is a purely verbal matter of how the

word 'red' is used.

Exercise 3: CommentaryExamples 1 and 3 are operating instructions and installation instructions,

respectively. They both relate to a piece of technology (software or hardware)

and provide instructions that facilitate its use. Examples 2 and 5 are abstract,

scientific (mathematical) or philosophical works. Although the do try to makeabstract concepts easier to understand, you can see that the form of writing is

very different. This is because they make demands on the reader that technical

writing cannot do. In this material, the reader is expected to ponder and think

about the text and to perhaps evaluate it critically. Technical writing, on the

other hand, must write for a reader whose mind is only partially on the text

his main concentration is on the system that he is trying to use.


6/21



1-6

Example 4 does relate to technology but it would be unusual for a technical

writer to write this type of material. Thats because it is not aimed at those

who need to implement the system (users, installation experts, programmers,

etc.) but rather at other developers. It is a kind of internal documentation

that exchanges ideas between those who already understand the context and

whose aims are to further the development of the product. Notice that it doesnot bother to present the ideas in a clear, easy to read format.

Characteristics of Technical Writing

Good technical writing facilitates the use of a product. But how does it do so?

What are the essential ingredients of good documentation? There are three

major characteristics of technical writing: Organization, Content and Style.

Each of these must contribute to the overall purpose of technical writing:

facilitating the use of the product.

Organization

How does organization contribute to the overall goal of technical writing,

making it easier to use the product?

Exercise 4: Organization of Technical DocumentsConsider the following documents: Examples 1 and 2 are technical documents

while Example 3 is a story. How does the organization of the technicaldocuments differ from that of the narrative? Why?


7/21



1-7

EXAMPLE ONE

Closing a FlockWhen you select Close Flock from the Open/Close Flock screen, you are prompted to save the dataabout the current flock with the following dialog boxes:

Options Description

Date box Enter the close flock date.Close Prompts to save Flock Close date only.Cancel Cancels the Close Flock activity, returns to

Open/Close Flock dialog box.Next Opens the second Save Flock History Data

dialog box.


8/21



1-8

EXAMPLE TWO

2.2 Configuring the MonitorOnce you have assembled the workstation, you must set your monitor to the following

specifications:

From the monitors controls (the buttons), change the following:

a. Brightness60

b. Contrast100

c. Color temperature6300

d. Picture effect (only in Sony screens) Dynamic

2.3 Installing the Camera

2.3.1 Automatic InstallationNormally, you can install a new camera automatically. To do this, you must make sure that you

possess a Camera Installation CD provided with the Camera.

1. Insert a Camera CD into the CDRW drive; the camera is automatically installed.

2. To activate the new camera, shut down the system and restart.

2.3.2 Manual InstallationYou can use the Service toolbar to manually install a new camera.

Warning

This option is not to be used in the Operating Room, but rather for special cases such asexhibitions and conferences. The Service toolbar lets you manually determine camerasettings.

Caution

Installing the camera manually, erases the automatic installation settings. Therefore, aftermanually installing the camera for an exhibition, you must reinstall it with automaticinstallation before using it in the operating room.

To install the camera manually:

1. Start the Service GUI and press Start to turn on the live image.

2. In the Service toolbar, click Adjust Camera Parameters; the Camera Settings screen appears:

!

!


9/21



1-9

EXAMPLE THREE

A Night in the DesertIt was the black of night and the kid was

running for all he was worth but I could see

that it was hopeless. He was worn out andbeat. He stopped short of the school and

raised his hand. A cluster of stars

silhouetted his slender frame.

I was still running, out front. Without stopping I

turned and yelled, "Hey come on you. Let's go.

Run, run!"

He stood there looking at me, not moving. I didn't

want to stop so I yelled again, "What's wrong!?"

To tell you the truth, I was feeling playful -- three

miles already and I wasn't the least bit tired. Yes, I

thought, I still had it in me, yes sir, I could still runand beat the kid. He was fourteen then and on the

fresh, boyish side of his teenage years: smooth skin

as yet unravaged by acne and stubble growth. I was

crazy about him, maybe because he had a

fresh air of confidence that I admired, I don't

know. I loved his eyes: large liquid eyes, like the

gaze of an antelope or deer. Innocent. He belonged

in the desert more than I. Like one of those pale-orange desert flowers that grow on the rocks here.

There was a dreamy innocence about him that I

liked. When I think of him I think of the Wadi

covered with light green spearmint and wild wheat

and barley. Natural things, wild things. Everything

here in the desert is light and clean and fragrant --

and undisciplined, like Avi.

Yeah I loved him, but really, but it was so good to

win! I trotted back to him proudly and clapped my

hands in his faced. "Come on, sissy, what's wrong

with you?" He blinked reproachfully.

"I just can't," he half whimpered. " I have astomach ache."

Exercise 4: CommentaryThe first two documents are organized to facilitate rapid information retrieval.

Material is organized into tables, into clearly numbered steps, and into short

sections with clear titles, often numbered. All of this permits the reader to

quickly find the information he is looking for. Notice that there are no large

blocks of text we dont want to force the user to actually read the text, lineby line. Notice that there are not more than a few paragraphs in each section.

We assume that the reader will quickly skim the text, find the needed

instruction or explanation, then put the book away the reader will not want

to get engrossed in this kind of material (despite that fact that learning how to

raise flocks of turkeys using computer programs may be interesting!).

Our third example shows the major difference between technical writing and a

story or novel. Notice that we are presented with large blocks of text with no

subdivisions we are expected to read the entire chapter, line by line because

the reader is expected to become engrossed in the story. The writing is therefor entertainment and the reader wants to read it in linear fashion, from

beginning to end, and not piecemeal as the need arises.


10/21



1-10

ACHIEVING RAPID INFORMATION RETRIEVAL

Let's consider some of the major organizational characteristics that facilitate

rapid information retrieval.

1. CLEAR DIVISIONSInformation is divided into formal divisions: Sections, subsections, tables,notes, operating procedures, etc. Divisions are marked off with separate titles

for each sections. Often, special typefaces, numbering or other desktop

publishing conventions enhance the demarcations.

2. RELEVANT TOPICSGood documentation must take into account how the reader will use the

document. For example, a Users manual for a software program is organized

around activities that the user would most likely want to accomplish with the

system. A reference manual, on the other hand, might be organized according

to commands arranged in alphabetical order.

3. HIERARCHICAL ORGANIZATION OF TOPICSTopics are arranged from the general to the specific. Each major section is

divided into minor sections, which are in turn divided into subsections, like

this:

1. Overview

1.1 How the database works

1.2 Database concepts

1.2.1 Records

1.2.2 Fields

1.2.3 Files

1.3 Connection between the database and the larger system

2. Installing the database

The above example shows hierarchy through what is known as legal

numbering: each subdivision is numbered and is preceded by the number of

the division of which it is a part. So, for example, the section titled Records, is

the first subdivision of Database concepts (1.2), which in turn is a subdivision

of Overview (1). The use of legal numbering to show hierarchy is common for

hardware documentation, but less used in manuals for software applications.


11/21



1-11

It is often more effective to show hierarchy through differences in the size,

font, and style of the titles themselves, rather than using just numbers.

What is important to remember is that hierarchy helps not only to locate the

information it also acts as a kind of commentary and facilitates

understanding as well. It promotes seeing the connection between conceptsand helps the reader put things into context.

Exercise 5: Organizing for Rapid Information RetrievalReorganize the following material so that it promotes rapid information

retrieval.

There are two main methods supported for helping you rid yourself of debt. These are

called the Debt Elimination Schedule and Loan Consolidation. Each of these terms and the

methods they employ are described below.

The Debt Elimination Schedule is designed to take all your current debt information and

project a possible solution for eliminating your debt. The solutions generally show

significant savings in interest (interest that does not go to the creditor) by following the

schedule instead of merely making the same current payments. Each of your debts is given

a priority. Each month, your payments are made to each debt. Once one debt is completely

paid off, then the payment that was earmarked for the paid off debt is then applied towards

the highest priority debt. This then accelerates the payment on the highest priority debt.

Loan acceleration (early payoff of a loan) is what produces your interest savings. To sum it

up--as debts are paid off, the payments for those debts are applied to the highest priority

debts that have not been paid off. Several options are available which can help accelerate

and optimize your debt elimination schedule. These include using minimum payments,

applying extra payments and selecting a priority method. You may choose one of 9

predefined priorities or you may enter your own priority by choosing the User Specified

option. The predefined methods are as follows:

The debts with the highest interest rates are paid off first.

The debts with the smallest balance are paid off first.

The debts with the largest balance are paid off first.

The debts with the smallest minimum payment are paid off first.The debts with the largest minimum payment are paid off first.

The debts with the smallest current payment are paid off first.

The debts with the largest current payment are paid off first.

Under the current conditions, the program determines how long it will take to payoff each

debt given the payment, balance and interest rate. Those debts which normally take the

shortest time to be paid off are given the highest priority to be paid off first.


12/21



1-12

Under the current conditions, the program determines how long it will take to payoff each

debt given the payment, balance and interest rate. Those debts which normally take the

longest time to be paid off are given the highest priority to be paid off first.

In many cases, the priority payoff option you choose will simply be a matter of preference.

However, certain options offer either real or psychological advantages. The Highest Rate

First should always yield the best results in terms of the amount of interest saved. Simplyput, the debts with higher rates are going to cost you more--so the sooner they are paid off,

the better off you will be. Many people advocate that you should pay off the smallest debts

first (select Smallest Debt First or Shortest Term Debt First). Your debts will begin to

disappear quicker giving you the feeling that you are accomplishing your goal--Getting out

of Debt! This satisfaction may be well worth the few extra dollars you may pay in interest

by not following the Highest Rate First method.

The Loan Consolidation Schedule is designed to take all your current debt information and

combine it into a single new loan. The new consolidated loan is presumed to have a lower

overall interest rate than the combined existing debts. It is the lower interest rate that

makes loan consolidation so appealing--it results in lower overall payments and less

interest paid on the loan. Credit cards typically have high interest rates associated with

them while Bank or Credit Union loans usually have much lower rates. It is therefore

relatively easy to take all your credit cards balances, add them up, get a new loan from a

bank, and payoff your credit cards. The bank loan will save you money through interest

savings. The Debt Analyzer allows you to create loan consolidation schedules and will

determine the amount of money you can save by doing so.

Several options are available to tailor the loan consolidation to your specific needs. These

options are made available through the loan consolidation method input field. Depending

on the method selected, you may have to enter a new monthly payment or the number of

months in the new loan.

Information about each debt is entered through the Debt Entry Window and includes the

name of the debt, minimum payment, current payment, balance, interest rate and a user

specified priority.


13/21



1-13

Content

Documentation for complex systems typically consists of three kinds of

content: Instructions

Explanations

Presentation of System Components (visual or textual presentations)

INSTRUCTIONSThe primary content of many types of manuals are Instructions. Examples of

such manuals are Users Guides, Maintenance Manuals, Installation Guides,

and Training Manuals. For example, the heart of a Users Guide is theoperating procedure. This is a sequence of instructions explaining how to use

a tool or function to accomplish a specific task.

The following instruction is an example of an operating procedure.

Locating a Record Using Search

To locate a record using Search:

1. Press S for search; the Search For menu appears.

2. Select Field Contents Match; the Select Search Fields dialog box appears

displaying all the field categories in the active database.

3. Select a field; a list of search operators is displayed.

4. Select a search operator (see Table 2 above) to display the search criteria

box.

5. Type the search value and press [Enter]; DataMaster searches the currently

opened database and highlights the first record containing the specified

value.

6. Press S to continue the search until all the records containing the specified

value have been located.


14/21



1-14

At this point we are not going to investigate the exact format and language of

an operating instruction (that comes in Lecture 3). Here I just want to point

out that the instruction confines itself to concrete actions that the user is to

perform to accomplish a specific task. Notice also that the steps are clearly

numbered and that they also contain references to the responses of the system

after an action is performed. This provides sign-posts to help orient the userand verify that the steps have been performed correctly.

EXPLANATIONSAlthough instructions are important, without accompanying explanations

many of them would be incomprehensible. A user, for example, must not only

be able to perform a task he must also decide whether the task is the one he

wants to perform at all. Explanations provide background, context,

information as to the results of performing a certain set of instructions, etc.

Without explanations, the user is just guessing that the task he is about toperform will lead to the desired results.

Here is an example of an explanation from Microsoft Word documentation:

Here the explanation does two things: it clarifies what Find Fast is, and it

explains some of the ramifications, or benefits, of using Find Fast. Not all

explanations are in paragraph format a syntax statement explains how to

type in a command, yet it consists of only one line of text.

In Lecture 3 we will learn how to write explanations and how to combine

different types of explanatory content.

REPRESENTATION OF SYSTEM COMPONENTSMuch of the information in technical documents consists of presentations of

system components. This can include the titles of sections throughout the

manual for example, if we think of a software system as a group of

activities, the components become actions that we can perform with the

system.. These, in turn, are reflected in the titles of the various sections in the

WHAT IS FIND FAST?Find Fast is a utility included with Microsoft Office that builds indexes to speed up

finding documents from the Open dialog box in any Microsoft Office program andfrom Microsoft Outlook. A Find Fast index consists of several hidden files that list

files, file properties, and file status. Because you create and maintain index files

through the Find Fast utility in the Control Panel, it's not necessary to work with the

index files directly in Windows Explorer.


15/21



1-15

manual and of course are represented in the table of contents. In other

instances, system components can be represented in a drawing (for hardware,

this may be an actual schematic), a table, or a simple bulleted list.

Representing system components provides the reader with information to

identify those parts of the system that he needs to use or relate to. These canenhance either instructions or explanations. We will look at how system

components are represented in later lectures, especially the lecture on writing

Overviews.

HOW DO YOU DECIDE ON CONTENT?The content of almost all technical documents is a mixture of instructions,

explanations, and presentations of system components. The way you combine

these is partly dependent on formal principles of structure that you will learn

about in later lectures. Content is also a function of the type of manual you are

writing. The following table lists some typical documents, their main purpose,and how their overall content is organized.

Document Purpose Organization

User Manual Complete guide to using a product. By Activity.

ReferenceManual

Provides more technical

information on each feature.

Alphabetically & by category.

Quick Reference For use by experienced user whileoperating the product.

By the interface or by some

easily identifiable categories.

Tutorial Teach skills needed to operate theproduct.

Lessons by skill or major

operation.

InstallationGuide

Install the system. By installation steps.

On-line Help Information on using a product. Hypertext

TechnicalPresentations

To explain the system to engineers

for CDRs, etc.

By slide according to the talk

being presented.

Site PreparationGuide

To prepare a site for installation of

the product.

Environmental topics.

Release Notes To inform customers (users) of

important information about thecurrent release that is not yet

included in the manual.

By topic.


16/21



1-16

Style

Good user documentation has a characteristic style. This should promote

rapid information retrieval and at the same time appears friendly, inviting the

user to read further. Style must also take into account what kind of

information to put in and what to leave out. This requires putting yourself inthe user's shoes: what does the user need to know to complete a task? What

information is essential, what trivial?

There are four elements of style that characterize good technical writing:

Terse

Friendly

Complete

Detailed

TERSE

Perhaps the hallmark of technical writing is its brevity instructions are

should confine themselves to the minimum words that you need to understand

how to carry out a task. Explanations are expected to be brief and to the point.

The idea is that since the reader is usually looking for very specificinformation, he does not want to bother to read more than he has to. For

example, the following operating procedure is short and to the point:

But paring words down to the minimum requires sensitivity to language and

an understanding of reader expectations. For example, the same operating

procedure as it is written on the following page violates natural language and

does not make it any easier for the reader:

To replace a selection with typing

1. Select the text you want to replace.

2. Type the replacement text.

Word replaces the highlighted selection

with the first character of the replacement


17/21



1-17

Here the writer left out the articles the and a something that makes the

piece sound more mechanical and less human. This type of style does not

contribute to rapid retrieval or understanding and therefore there is no real

justification for it. It is a typical case of trying to sound technical.

An even more extreme case would be the following:

Here the problem lies not only in language, but in the loss of information. Do

not remove important information for the sake of brevity! We will learn more

about this in the coming lectures.

FRIENDLY

Another characteristic of good technical writing style is that it seemsfriendly to the user. Many readers are put off by technical information

looking through unfamiliar material and trying to understand it well enough

to apply it, can be daunting even for technical people. Much of the fear can be

eliminated through language that treats the reader as a human being rather

than as a machine, and by a format that is easy to read and that does not

appear too complex.

To replace selection with typing

1. Select text to replace.

2. Type replacement text.

Word replaces highlighted selection with

first character of replacement text.

To cook egg:

1. Drop egg in water.

2. Cook.

3. Remove egg.


18/21



1-18

For example, consider the following passage:

This piece is part of an explanation about Words formatting features. Notice

that it directly addresses the reader you use. This helps capture the

readers attention and make him feel that the writer has his interests at heart

the text is not just describing something, but communicates that it is trying to

help the reader.

On the other hand, you should not be mislead into thinking that being friendlymeans becoming too familiar this actually leads to annoyance as the next

passage illustrates:

This above passage might be OK for a brochure or an ad, but it is certainly

not appropriate for a technical manual. Someone looking for information doesnot want to be sold and waste time picking through advertising copy! I have

actually read manuals like this and after reading a few pages like this, you just

dont want to use the manual again.

DETAILED

If anything, technical writing must be detailed. Unlike other forms of writing

(such as fiction), you cannot leave anything to the imagination. I have found

that the best technical writers are the ones who are perpetually worried thatthey may have not spelled everything out clearly enough they are concerned

that there may be come ambiguity in a passage and are careful to go over their

work to make sure that there are no loose edges. The bottom line is that you

should not assume that the reader understands you. For example, compare the

following passages:

You use Word's Formatting features to give your documents a

more professional look. Through the control of font, spacing and

other elements you can quickly produce well designed, effectivepage layouts.

You use Word's Formatting features to give your documents a

more professional look. Through the control of font, spacing and

other elements you can quickly produce well designed, effectivepage layouts.

With the Object Inspector you can do some really amazing things

like changing the properties of your document's object. You won't

believe the changes you can make!


19/21



1-19

This example lacks detail we dont know where to position the insertion

point, we dont know where the Print command is found, etc. The following

passage is better (the new details are highlighted):

The writing is still short and to the point, but now the guess work has been

eliminated for the reader.

On the other hand, do not think that detail means introducing trivial

statements like the following:

To print the current page of a document:

1. Position the insertion point.

2. Choose Print.

3. Select Current Page or Selection.

4. Choose OK.

To print the current page of a document:

1. Position the insertion point in the page you want to print.

2. In the File menu, choose Print. The Print dialog box appears.

3. In the Print dialog box, select the Current Page option.

4. Choose OK.


20/21



1-20

Here the passage introduces too many details to give proper instructions we

have to assume a certain amount of knowledge on the part of the user. For

example, here we have to assume that the reader knows how to use the mouse.

We learn more about assessing the level of the audience in later lectures.

COMPLETE

By complete, I meant that the writing should cover as much ground as

necessary to be clear. For an instruction, this means not only vital details as

we saw in the previous examples, but also the systems responses to the users

actions as highlighted in the following passage:

To select an option:

1. Place your hand on the mouse and move the mouse until the mouse

cursor rests on an option.

2. With the index finger of the same hand press down on the left mouse

button; the button clicks and the option is simultaneously selected. You

may now select a sub option.

To create a master password for the table:

1. In the Table Properties list, choose Password Security.

2. Choose Define to display the Password Security dialog box.

3. Type the password you want in the Master Password text box. You willsee asterisks (*) representing the characters you type. A password can be

from 1 to 31 characters long and can contain spaces.

4. Type the same password in the Verify Master Password text box. Again,you will see asterisks in place of the characters you type.

Choose OK to close the dialog box and return to the Create Table dialog box.


21/21



1-21

On the other hand, in most types of documentation, you must make sure not to

be repetitive. Except for Training Manuals where repetition can sometimes be

useful for teaching a skill, technical documents should state things clearly

once you need not repeat the same point again and again just to make sure

that the reader understood your meaning.

Exercise 6: Analyzing style

Analyze the style of the manual attached to this lecture.

Identify the various stylistic elements discussed above and decide whether the

piece is an example of good or bad documentation. (Your analysis should be

general you do not have write more than about a page.)