Technical Writing Principles and Techniques by drmati

VIEWS: 23,942 PAGES: 21

More Info
									Lecture One: Principles of Technical Writing

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 people’s 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 reader’s 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 User documentation. 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.

© YEDA School for Technical Communications

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 to how you use manuals and complete the following exercise. Exercise 1: Understanding User Documentation Describe 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: Commentary The 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., they try 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 it’s 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 don’t like to read technical manuals and they 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: Ramifications How does the way of using documentation affect the way we write it? What are the major characteristics that documentation should have? Exercise 2: Commentary Since 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:

Principles of Technical Writing

© YEDA School for Technical Communications

1-3

• The writing should be clear and easy to understand since the user does not 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 appropriate information 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 without detracting 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 has to “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.

Principles of Technical Writing

© YEDA School for Technical Communications

1-4

Definition of Technical Writing
The following definition provides us with criteria for evaluating technical writing:

Technical Writing
Instructions and/or descriptive material relating to a particular product 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: does the 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 Writing Compare 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 2 Press Shift+F1; the pointer changes to a question mark. 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."

Principles of Technical Writing

© YEDA School for Technical Communications

1-5

Example 3
Connecting the Printer to a Computer 1 2 3 4 Insert the 36-pin plug into the parallel interface connector on the right back of the printer. Snap the 2 wire clips onto the plug to make a secure connection. Connect the other end of the cable to a computer. 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, an increase 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 connectedword 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: Commentary Examples 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 make abstract 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.
Principles of Technical Writing

© YEDA School for Technical Communications

1-6

Example 4 does relate to technology – but it would be unusual for a technical writer to write this type of material. That’s 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 does not 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 Documents Consider the following documents: Examples 1 and 2 are technical documents while Example 3 is a story. How does the organization of the technical documents differ from that of the narrative? Why?

Principles of Technical Writing

© YEDA School for Technical Communications

1-7

EXAMPLE ONE
Closing a Flock
When you select Close Flock from the Open/Close Flock screen, you are prompted to save the data about the current flock with the following dialog boxes:

Options Date box Close Cancel Next

Description Enter the close flock date. Prompts to save Flock Close date only. Cancels the Close Flock activity, returns to Open/Close Flock dialog box. Opens the second Save Flock History Data dialog box.

Principles of Technical Writing

© YEDA School for Technical Communications

1-8

EXAMPLE TWO 2.2 Configuring the Monitor
Once you have assembled the workstation, you must set your monitor to the following specifications: • From the monitor’s controls (the buttons), change the following: a. Brightness b. Contrast 60 100 6300˚

c. Color temperature

d. Picture effect (only in Sony screens) – Dynamic

2.3 Installing the Camera
2.3.1 Automatic Installation
Normally, 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 Installation
You 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 as exhibitions and conferences. The Service toolbar lets you manually determine camera settings.

!

Caution
Installing the camera manually, erases the automatic installation settings. Therefore, after manually installing the camera for an exhibition, you must reinstall it with automatic installation 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:

Principles of Technical Writing

© YEDA School for Technical Communications

1-9

EXAMPLE THREE
A Night in the Desert It 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 and beat. 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 run and 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 paleorange 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 a stomach ache."

Exercise 4: Commentary The 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 don’t want to force the user to actually read the text, line by 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 there for entertainment and the reader wants to read it – in linear fashion, from beginning to end, and not piecemeal as the need arises.

Principles of Technical Writing

© YEDA School for Technical Communications

1-10

ACHIEVING RAPID INFORMATION RETRIEVAL Let's consider some of the major organizational characteristics that facilitate rapid information retrieval. 1. CLEAR DIVISIONS Information 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 TOPICS Good documentation must take into account how the reader will use the document. For example, a User’s 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 TOPICS Topics 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.
Principles of Technical Writing

© YEDA School for Technical Communications

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 concepts and helps the reader put things into context.

Exercise 5: Organizing for Rapid Information Retrieval Reorganize 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.

Principles of Technical Writing

© YEDA School for Technical Communications

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. Simply put, 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.

Principles of Technical Writing

© YEDA School for Technical Communications

1-13

Content
Documentation for complex systems typically consists of three kinds of content: Instructions Explanations Presentation of System Components (visual or textual presentations) INSTRUCTIONS The primary content of many types of manuals are Instructions. Examples of such manuals are User’s Guides, Maintenance Manuals, Installation Guides, and Training Manuals. For example, the heart of a User’s Guide is the operating 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.

Principles of Technical Writing

© YEDA School for Technical Communications

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 user and verify that the steps have been performed correctly. EXPLANATIONS Although 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 to perform will lead to the desired results. Here is an example of an explanation from Microsoft Word documentation: 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 and from 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.

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 COMPONENTS Much 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
Principles of Technical Writing

© YEDA School for Technical Communications

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 can enhance 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 User Manual Reference Manual Quick Reference Tutorial Installation Guide On-line Help Technical Presentations Site Preparation Guide Release Notes Purpose Provides more technical information on each feature. For use by experienced user while operating the product. Teach skills needed to operate the product. Install the system. Information on using a product. To explain the system to engineers for CDRs, etc. To prepare a site for installation of the product. To inform customers (users) of important information about the current release that is not yet included in the manual. Organization Alphabetically & by category. By the interface or by some easily identifiable categories. Lessons by skill or major operation. By installation steps. Hypertext By slide according to the talk being presented. Environmental topics. By topic.

Complete guide to using a product. By Activity.

Principles of Technical Writing

© YEDA School for Technical Communications

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 in the 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 it’s 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 specific information, 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: 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 text. 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:
Principles of Technical Writing

© YEDA School for Technical Communications

1-17

To replace selection with typing 1. Select text to replace. 2. Type replacement text. Word replaces highlighted selection with first character of replacement text. 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: To cook egg: 1. Drop egg in water. 2. Cook. 3. Remove egg.

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 seems “friendly” 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.

Principles of Technical Writing

© YEDA School for Technical Communications

1-18

For example, consider the following passage: 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, effective page layouts.

This piece is part of an explanation about Word’s formatting features. Notice that it directly addresses the reader “you use…”. This helps capture the reader’s 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 friendly means becoming too familiar – this actually leads to annoyance as the next passage illustrates: 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! 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 does not 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 don’t 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 that they 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:

Principles of Technical Writing

© YEDA School for Technical Communications

1-19

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.

This example lacks detail – we don’t know where to position the insertion point, we don’t know where the Print command is found, etc. The following passage is better (the new details are highlighted):

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.

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:

Principles of Technical Writing

© YEDA School for Technical Communications

1-20

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.

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 system’s responses to the user’s actions as highlighted in the following passage: 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 will see 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.

Principles of Technical Writing

© YEDA School for Technical Communications

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.)

Principles of Technical Writing


								
To top