Upload
mati
View
228
Download
0
Embed Size (px)
Citation preview
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.
8/6/2019 Technical Writing Principles and Techniques
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:
8/6/2019 Technical Writing Principles and Techniques
3/21
YEDA School for Technical Communications
Principles of Technical Writing
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.
8/6/2019 Technical Writing Principles and Techniques
4/21
YEDA School for Technical Communications
Principles of Technical Writing
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."
8/6/2019 Technical Writing Principles and Techniques
5/21
YEDA School for Technical Communications
Principles of Technical Writing
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.
8/6/2019 Technical Writing Principles and Techniques
6/21
YEDA School for Technical Communications
Principles of Technical Writing
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?
8/6/2019 Technical Writing Principles and Techniques
7/21
YEDA School for Technical Communications
Principles of Technical Writing
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/6/2019 Technical Writing Principles and Techniques
8/21
YEDA School for Technical Communications
Principles of Technical Writing
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:
!
!
8/6/2019 Technical Writing Principles and Techniques
9/21
YEDA School for Technical Communications
Principles of Technical Writing
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.
8/6/2019 Technical Writing Principles and Techniques
10/21
YEDA School for Technical Communications
Principles of Technical Writing
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.
8/6/2019 Technical Writing Principles and Techniques
11/21
YEDA School for Technical Communications
Principles of Technical Writing
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.
8/6/2019 Technical Writing Principles and Techniques
12/21
YEDA School for Technical Communications
Principles of Technical Writing
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.
8/6/2019 Technical Writing Principles and Techniques
13/21
YEDA School for Technical Communications
Principles of Technical Writing
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.
8/6/2019 Technical Writing Principles and Techniques
14/21
YEDA School for Technical Communications
Principles of Technical Writing
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.
8/6/2019 Technical Writing Principles and Techniques
15/21
YEDA School for Technical Communications
Principles of Technical Writing
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.
8/6/2019 Technical Writing Principles and Techniques
16/21
YEDA School for Technical Communications
Principles of Technical Writing
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
8/6/2019 Technical Writing Principles and Techniques
17/21
YEDA School for Technical Communications
Principles of Technical Writing
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.
8/6/2019 Technical Writing Principles and Techniques
18/21
YEDA School for Technical Communications
Principles of Technical Writing
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!
8/6/2019 Technical Writing Principles and Techniques
19/21
YEDA School for Technical Communications
Principles of Technical Writing
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.
8/6/2019 Technical Writing Principles and Techniques
20/21
YEDA School for Technical Communications
Principles of Technical Writing
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.
8/6/2019 Technical Writing Principles and Techniques
21/21
YEDA School for Technical Communications
Principles of Technical Writing
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.)