Simon Fraser University - ensc.sfu.ca

2

Simon Fraser University

3

School of Engineering Science

CopyrightCopyright 1999 by Steve Whitmore and Susan Stevenson. All rightsreserved. Copies of this module are available for a nominal fee from theSchool of Engineering Science, Simon Fraser University, Burnaby, BritishColumbia, V5A 1S6, Canada, Phone: (604) 291-4371; FAX: (604) 291-4951. Theauthors may be contacted directly at the following:

Steve WhitmoreOffice: ASB 9872(604) 291-4946 (W)(604) 939-4562 (H)E-mail: [email protected]

Susan StevensonOffice: ASB 9874(604) 291-3816 (W)E-mail: [email protected]

AcknowledgmentsThis module is a collaborative effort involving many of the faculty, staff, andstudents (past and present) in the School of Engineering Science at SimonFraser University. While Doug Girling and Andrew Rawicz deserve specialthanks for their contributions to this module, we cannot hope to name every-one else who deserves to be acknowledged. So we offer a collective thankyou to all the ENSC faculty, staff, and students who have offered their sug-gestions, questions, criticism, and encouragement. We hope you will con-tinue to point out ways in which we can improve subsequent editions.Thank you.

4


5


Contents

Copyright...............................................................................................................3

Acknowledgments................................................................................................3

List of Figures and Tables ...................................................................................7

Preface....................................................................................................................9

1. Chapter One: Collaborative Writing............................................................ 111.1. Collaborative Writing ...................................................................... 13

1.1.1. Why Write Collaboratively? ............................................ 131.2. Listening Skills ................................................................................. 14

1.2.1. Listening Actively............................................................. 141.2.2. Other Points to Consider about Listening...................... 171.2.3. When to Not Listen .......................................................... 20

1.3. Team Dynamics ............................................................................... 211.3.1. Articulating Goals ............................................................ 211.3.2. Team Interaction............................................................... 231.3.3. Team Roles and Leadership ............................................ 231.3.4. Division of Labor .............................................................. 251.3.5. Team Responsibility ......................................................... 251.3.6. Team Conflicts .................................................................. 26

1.4. Writing as Part of a Team................................................................ 281.4.1. When to Use a Team Writing Strategy ........................... 291.4.2. How the Collaborative Writing Process Operates......... 301.4.3. Collaborative Planning..................................................... 301.4.4. Collaborative Revision ..................................................... 33

2. Chapter Two: Project Documentation ......................................................... 372.1. Project Documents ........................................................................... 39

2.1.1. Introduction ...................................................................... 392.1.2. A Creative Digression ...................................................... 452.1.3. Project Phases and Project Documentation.................... 562.1.4. Proposals ........................................................................... 582.1.5. Functional Specifications ................................................. 612.1.6. Design Specifications........................................................ 632.1.7. User’s and Technical Manuals......................................... 652.1.8. Progress Reports............................................................... 702.1.9. A Final Point about Project Documentation................... 70

6


3. Chapter Three: Formatting for the Reader ..................................................723.1. The Importance of Form..................................................................74

3.1.1. The Relationship between Form and Content................743.1.2. Rhetorical Form and Community ...................................763.1.3. Rhetorical Form as Dynamic ...........................................773.1.4. Rhetorical Form as Static..................................................783.1.5. Mastering the Technology ...............................................80

3.2. Writing to Inform .............................................................................823.2.1. Readers and Information Processing ..............................83

3.3. General Principles of Format...........................................................973.3.1. White Space.......................................................................973.3.2. Organization....................................................................1063.3.3. Graphical Elements.........................................................1133.3.4. Referencing Information Sources ..................................118

7


List of Figures and Tables

Figure 1: Free-Writing Sample ........................................................................... 49Figure 2: Example Mind Map (Bug Diagram).................................................. 51Figure 3: Initial Puzzle Layout ........................................................................... 52Figure 4: Puzzle Solution.................................................................................... 53Figure 5: The 1st Post-It Note® ............................................................................ 54Figure 6: Example of a Gantt Chart ................................................................... 61Figure 7: Example of a Milestone Chart............................................................ 61Figure 8: Example of a System Block Diagram................................................. 65Figure 9: Example Warning Message................................................................ 67Figure 10: Example of a Less-Than-Helpful User’s Manual............................ 69Figure 11: Style Dialogue Box (Microsoft Word 7.0) .......................................... 81Figure 12: How Style and Form Affect Communication ................................. 84Figure 13: Buttons in On-Line Documentation................................................. 90Figure 14: Using Figures to Explain Concepts ................................................. 94Figure 15: Example of Cognitive Interference .................................................. 95Figure 16: Spatial Relationships between Headings and Text ........................ 97Figure 17: Spatial Relationship between Figure Labels and Text ................... 98Figure 18: Texts with Contrasting Amounts of White Space .......................... 99Figure 19: Detail of Serifs.................................................................................. 100Figure 20: Word Pattern Recognition for Sans Serif versus Serif Fonts........ 101Figure 21: Comparison of the Readability of Selected Fonts......................... 101Figure 22: The Problem with Using Only Upper Case .................................. 102Figure 23: Alternative Paragraph Conventions.............................................. 104Figure 24: Full Justification versus Ragged Right Margin............................. 105Figure 25: The Problem with Underlining Headings..................................... 107Figure 26: Accommodating Four Heading Levels ......................................... 108Figure 27: Conventions for Page Numbering................................................. 109Figure 28: Sample Table of Contents ............................................................... 111Figure 29: Sample List of Figures and Tables ................................................. 112Figure 30: Data Presented in Text Form.......................................................... 113Figure 31: Example Table with Context on Left ............................................. 113Figure 32: Example Table with Context on Right........................................... 114Figure 33: Placement of Labels for Figures and Tables.................................. 114Figure 34: Example of a Graph ........................................................................ 116Figure 35: Example of a Table .......................................................................... 116

Table 1: Stages in Team Development............................................................... 22Table 2: Symptoms of Groupthink .................................................................... 27Table 3: Project Phases and Project Documentation......................................... 57Table 4: Patterns of Organization....................................................................... 88Table 5: Selected Examples of Fonts ................................................................ 100

8


9


PrefaceROJECT DOCUMENTATION AND COLLABORATIVE WRITING is thethird module in a series of four modules that we have written foryou, the students of Engineering Science at SFU. Your comments

about writing and your needs as writers have guided and informed ourwriting of these modules. We have used examples from your work and con-sidered the contexts specific to the kinds of documents required forEngineering Science and for industry. In addition, we have provided specificsolutions to some of the more common problems we see in the writingturned in to us and other ENSC faculty.

The first chapter in this module, “Collaborative Writing,” provides you withsome general information about writing as part of a team, group dynamics,conflict resolution, and basic listening skills.

Chapter Two, “Project Documentation,” details how to write some of thedocuments you will be expected to produce in industry and for your projectcourse: Proposals, Functional Specifications, Design Specifications, User’sand Technical Manuals, and Progress Reports. In addition, it contains someinformation about problem analysis and thinking creatively.

Chapter Three, “Formatting for the Reader,” explains why we place so muchstress on the appearance of your documents and points to a number of theways in which form influences the comprehension of readers. It also offerssome advice on learning how to format effectively and provides generalguidelines for documents written for the Engineering Science program.

The other three modules, which you will be provided as requiredthroughout your course of studies, cover the following topics:

Module One: Communication Skills for Engineering StudentsModule Two: Report Writing and Employment InformationModule Four: Writing Theses and Thesis Proposals

We wish you all the best, both in your current studies as well as in your fu-ture career as an engineer.

Steve and Susan

¦

P

10


1. Chapter One: Collaborative Writing


12

13


1.1. Collaborative Writing

[ Introduction[ Listening Skills[ Group Dynamics[ Team Writing

1.1.1. Why Write Collaboratively?

FFECTIVE STRATEGIES FOR WORKING AND writing as part of a teamare essential for those entering the engineering profession. What-ever your field of engineering, you can expect to spend a great deal

of time working in teams on all aspects of projects from planning to final re-ports. Because the success of many engineering projects depends on effectiveteamwork, well-developed interpersonal and communication skills can be asimportant to a successful engineering career as a firm foundation in mathe-matics and science.

The best way to develop good team skills is by working (and writing) inteams. And so, project courses and team assignments are common aspects ofengineering education. If you have already worked on a project team, youmay have enjoyed the experience and have helped achieve a feat far beyondwhat you could have accomplished on your own.

On the other hand, you may have found the experience frustrating and spentmore time dealing with personalities than working on achieving your goal. Ifyou think back on the experience, you will likely note that the communica-tion and interpersonal skills of one or more members helped determine thefinal result. We have seen teams deal very well with difficult individuals andmanage to make the experience positive for all members and the project asuccess. And we have seen teams with great potential fall apart and projectsfail because the team members failed to listen to and respect each other.

You can help ensure the success of a team if you have the ability to listencarefully, to encourage others to participate, to accept criticism, to take re-sponsibility, to resolve disputes, and, when appropriate, to lead. The fol-lowing sections of listening skills and team dynamics suggest strategies fordeveloping and applying these abilities. As you read on, think of situationsin which you could have applied the strategies suggested.

The chapter ends with a section focusing on collaborative writing strategies.Keep in mind that the ability to listen and to contribute to building an effec-tive team are the foundations of any collaborative endeavor, including writ-

E


14

ing. The same basic skills apply. And good collaborative writing skills, likeall other team skills, develop through practice. So, we urge you to take ad-vantage of all opportunities to work as part of team, whether with a partneror as part of a larger team. When difficulties arise, accept the challenge of-fered and approach disagreements as problems you can solve. And keep inmind that the more you challenge yourself, the faster you develop crucialmentoring and leadership abilities that will serve you well throughout yourcareer.

1.2. Listening SkillsOne of the most important skills you must master to work capably as part ofa team is the ability to listen effectively. Effective listening skills underpinthe ability of any team to resolve disagreements and to meet their goals.When team members fail to listen to each other, minor disagreements cangrow into disputes and goals may fail to be defined. What has sometimesbeen described as a “breakdown in communication” is often simply a failure tolisten.

Unfortunately, the traditional educational system devotes far more attentionto teaching us to read, write, and speak than it does to teaching us how tolisten. Perhaps part of the reason for this neglect is that listening is oftenmisunderstood to be a passive activity. But, in fact, listening effectively re-quires that you take an active role in conversations, that you become fully en-gaged in what is being stated and try to understand what is being left un-stated. And make no mistake, listening carefully is hard work – at least ashard as giving a presentation. The following section aims to provide youwith some of the skills involved in active listening.

1.2.1. Listening Actively

In order to become an effective member of any team, whether engaged inwriting or not, you must learn to listen actively. That is, you must interactwith the speaker by asking questions and providing verbal as well as non-verbal feedback. You must appear vitally interested in what the speaker issaying, and you must clearly communicate that interest to the speaker.Learning to listen actively has several advantages.

First, it helps ensure that you fully understand what is being said. Second,by actively engaging the speaker with questions etc., you increase thelikelihood that he or she will provide more complete information than mightotherwise be the case. Third, your interest in what speakers have to say oftenhas the effect of encouraging them to listen more closely to what you have tosay.

You can communicate your interest by using attending responses, open-ended responses, tracking responses, and summarizing responses.

15


1.2.1.1. Attending Responses

Attending responses are verbal and non-verbal indicators which communicateyour interest in what the speaker is saying. These types of responses simplyindicate to the speaker that you are carefully paying attention to them. Forexample, your tone of voice can quickly indicate whether or not you are in-terested. We suggest that you use a warm, informal, tentative, and friendlytone. In general, you should address the speaker by their first name – we alllike to be called by name. You can also make occasional use of “uh-huh,”“yes,” “I see,” etc. to indicate to the speaker that you are following what theyare saying. But you should also be careful not to overdo the “uh-huh’s.” At-tentive silence is sometimes more useful than too many grunts.

Unless you know the speaker well enough to use specialized language, keepyour statements and questions short and easy to understand. For example,say “talk” instead of “communicate” and “write” instead of “correspond.” And,where appropriate, avoid specialized jargon (i.e., technobabble). This last pointis particularly important if you are listening to non-specialists or potentialusers explain their needs for a device or system that you might be develop-ing for them. And , above all, recognize that if you are speaking more thanhalf of the time, then you probably aren’t listening effectively.

In addition to those verbal responses, you can also use some of the followingnon-verbal techniques to indicate that you are paying attention:

• Positive head nods;• Facial expression suitable to the topic;• Head tilted slightly;• Open posture (rather than arms crossed);• Regular eye contact (but don’t stare);• Palms open (rather than clenched fist or fidgeting);• Gestures used appropriately;• Touch used when appropriate;• Smiling (rather than tightness or excessive smiling);• Close proximity (arm’s length).

Appropriate use of these techniques enable speakers to feel comfortable pro-viding you with information and also help them recognize when you are notfollowing what they are saying.

1.2.1.2. Open-Ended Responses

Open-ended responses are usually questions which require more than a “yes”or a “no” or a statement of fact in response to them. These sorts of questionsencourage a speaker to expand upon their subject and generally start with astated or implied “what” or “how.” For example, you might ask “What solu-tions have you thought of?” rather than “Have you thought of this solution?” Thefirst question allows the speaker to expand upon the subject, and you gainmore information than with the second question which may be answered


16

with a simple “yes” or “no.” The point is to gain as much useful informationas possible. Because they enable speakers to provide more information, thesesorts of questions are especially helpful when you are developing a systemor device for a client or when you are working with the potential users of asystem or device.

• Would you like to talk about . . . ?• Where would you like to begin?• Could you tell me what that means?• What do you imagine . . . ?• What have you thought of?• What would it be like . . . ?• How do you see things changing?• What would you like to do about . . . ?• I’m wondering . . . ?• What’s that like?• What can you think of?

However, you should also be somewhat cautious when asking questions.Asking too many questions may lead the speaker to suspect you are interro-gating them or challenging them rather than seeking information. And avoidleading questions which require the speaker to agree with you (i.e., “Youdon’t really want to do that, do you?”). Also avoid over-using “why” questions.“Why” questions can imply that you are judging the speaker and may placethe speaker in the position of defending their position. Consider, for exam-ple, the difference between “Why didn’t you try to solve the problem that way?”and “What happened when you tried that solution?” The question beginningwith “Why didn’t you . . . ” can imply to the speaker “You should have . . . .”

1.2.1.3. Tracking Responses

Tracking responses take three forms – reflecting, clarifying, and silence – andhelp the speaker persist upon a particular topic. You can use reflecting tocheck your understanding of what the speaker is saying. With this sort ofstatement, you rephrase as a question the feelings, the content, or the wordsof the speaker’s message. Reflecting statements generally take the form of“You say . . . ,” “You mean . . . ,” or “You feel . . . .” For example, if someone onyour writing team came to you to complain that another team member wasnot doing their fair share of the work, you might respond in one of the threefollowing ways:

• You say John is lazy?• You mean John hasn’t completed his part of the design specs?• You feel angry because John isn’t doing his fair share of the work?

Clarifying is used to gather further information about something a speakerhas said which is unclear or confusing. For example, you might say “Correctme if I’m wrong, but . . .” or “. . . is that what you mean?” These sorts of ques-

17


tions also indicate to the speaker that you want to understand what they aresaying and encourages them to elaborate upon the point.

Silence is also a useful tracking response. In most everyday conversations, aone second pause between the end of one person speaking and thebeginning of another person speaking is typical. If you slightly increase theduration of your pauses, you convey your interest in giving the speaker lotsof “talking room.” Further, many people find excessive silent pauses in aconversation to be disconcerting, so they will tend to continue speaking. Thistechnique is often used by experienced interviewers. Of course, you mustalso exercise some caution when using silence because excessive silence mayindicate a lack of interest in or a lack of attention to the speaker and canquickly bring a conversation to an end.

1.2.1.4. Summarizing Responses

Summarizing responses are ways to review the information that has beencovered in the conversation and provides an opportunity to move on to an-other topic or to add on to what has already been discussed. Summarizingfunctions as an important reality check and allows the speaker to correct anymisunderstandings you may have about what they are saying. In general,you employ this technique by briefly summarizing the conversation andthen asking a question like “Is that accurate?” After asking this question,pause for five or ten seconds to allow the speaker ample opportunity torespond.

1.2.2. Other Points to Consider about Listening

Beyond the general advice that you learn to listen actively, you should alsogive some thought to several other issues in relation to listening. The fol-lowing six points provide some additional information about listening skills.

1.2.2.1. Minimizing Distractions

Part of being a good listener involves creating a good environment for lis-tening. Sometimes distractions are unavoidable, but insofar as possible weshould minimize those over which we have control. If we are having an im-portant meeting, we should shut the door or move to a quieter location inorder to minimize noise. Similarly, telephones could be put on call-forwardand a do-not-disturb sign could be placed on the door. These sorts of actionshelp create an optimum environment for listening.

On a more individual level, we should avoid fiddling with papers or bookswhen someone is speaking (although we may want to take notes). As muchas possible, the goal is to devote your undivided attention to the speaker. Ifyou are attempting to divide your attention between the task of listening andsome other task, you are doing neither effectively. If other tasks are more


18

immediate, then perhaps you should tell the speaker you are busy and setup a time to talk with them later.

1.2.2.2. Listening with Respect

You should communicate to the speaker that you respect them, particularlyif the speaker is angry or otherwise upset. Respect their opinions andsuggestions even if you disagree with them or have reservations about them.Hear out their ideas and acknowledge the strengths of their ideas. As thespeaker continues and expands upon their ideas, you may well discoverthat, once fully explained, their ideas make more sense than you firstthought.

Initially, you should avoid pointing out any contradictions or inconsistenciesin the speaker’s statements. Later in the conversation, you may expressdoubts, but expressing them in the form of questions is usually most effec-tive. For example, a question such as “How do you think that will work?” is al-most always better than a statement like “That won’t work!” That last re-sponse simply has the effect of cutting off the conversation and preventingthe further exploration of ideas.

And, whatever you do, always respect the feelings of a speaker, even if youdon’t understand them. Everyone has the right to their feelings. We recom-mend that you be non-judgmental of the speaker’s feelings otherwise he orshe may be reluctant to continue the conversation.

Obviously, we must pay attention to the content that is being expressed by aspeaker; however, we are likely to be most effective listeners if we also payattention to the feelings associated with the content. When we can identifythe feelings that underlay the speaker’s statements, we can begin to under-stand their frame of reference.

The feelings that a speaker attaches to a subject communicate essential in-formation about the content: its importance, its accuracy, etc. If a speakersounds excited about a subject, then the subject is usually quite important tothem, and you should respond accordingly. Let them know that you sharetheir enthusiasm. If the speaker sounds confused, you can ask questionswhich help them clarify their ideas.

And we must remember that most speakers do not reveal their feelings ver-bally; generally, the feelings are expressed on a non-verbal level that we canidentify by listening to their voice – speed, tone, emphasis, loudness – andtheir body language – posture, facial expressions, etc. By considering thespeaker’s feelings, you can place the content into the broadest possiblecontext.

19


1.2.2.3. Avoiding Assumptions

We must not assume that we understand what a speaker is saying. State-ments such as “I know exactly what you mean” typically have the effect of cut-ting off the speaker. After all, what is the point of the speaker telling yousomething if you claim to already know it? Generally, we don’t know exactlywhat the speaker means, even if we are familiar with the subject. Thespeaker may have a new perception about the subject or may communicatedetails with which we are unfamiliar.

We often have a natural tendency to want to show the speaker that we knowsomething about the topic under discussion. But if we interrupt the speaker,we will not obtain all the necessary information from them. Jumping aheadand making assumptions can easily make us appear rude or even ignorantwhen we base our response on mistaken assumptions.

As much as possible, we should force ourselves to listen to the main ideas, tosummarize them in our minds, and to avoid mentally looking for answers aswe listen. We should avoid defining the nature of a problem too quickly orproposing solutions too quickly. Until we have sufficient information, ourpossible solutions are, at best, a guess. In the words of H. L. Mencken, “forevery problem, there is a solution that is simple, plausible, and wrong.” Inother words, hasty solutions rarely work.

1.2.2.4. Avoiding Superficial Reactions

We can’t help noting the external features of a someone’s style – their cloth-ing, posture, mannerisms, accents, etc. However, if we are excessively dis-tracted by how someone looks or sounds, we may miss what the person hasto say. In other words, we should avoid attending solely to appearances.

In addition, we should become aware of our biases and prejudices. We allpossess them. But when we have these emotional reactions to a speaker ortheir topic, we may stop listening and start mentally refuting their words inour heads. By becoming aware of our biases, we can learn to avoid “tuningout” when certain issues are raised. By trying to focus on the issues at handand not on your initial reactions to them, you increase the chances of morefully understanding why the topic matters.

1.2.2.5. Putting Facts into Context

In Engineering, we are taught a deep respect for facts, and we are alsotaught to correlate these facts to see whether or not any general conclusionscan be drawn from them. Unfortunately, this training may lead us to focuson the facts rather than the context into which the speaker places them. Toplace the facts you hear into a proper context, you should listen for severalminutes before responding so that you have a general understanding of thesubject before you decide what is important and what the facts might mean.


20

1.2.2.6. Remaining Focused

Typically, we speak at the rate of about 125 words per minute. Yet we canthink at a rate of 400 to 500 words per minute (even faster when we think inimages and concepts rather than words). Consequently, we can listen to thespeaker and still have time to think about other things, perhaps what we willhave for dinner or how we will finish our next paper on time. Unfortunatelythese sorts of digressions can make it difficult for us to remain focused.

If we catch your minds wandering, we should immediately return our atten-tion to the speaker. Further we should also avoid faking attention to thespeaker. Most of us can appear attentive by nodding our heads, smiling, etc.,while our thoughts are on other things. Almost inevitably, however, thespeaker will ask you a question that reveals you are not listening. Shouldthat happen or if your attention has momentarily drifted, you should ask thespeaker to repeat the information you missed.

Another way to ensure that you remain focused is by taking notes. The act ofwriting something down helps us to remember it. Further, before we cansummarize something in writing, we must usually understand preciselywhat the speaker is saying. We must be sure, however, that our note-takingis properly organized. Otherwise, we will end up with an inaccurate sum-mary or a disorganized outline.

If you are in the habit of doodling while taking notes, you should monitor theamount of drawing you do while listening to someone. An excess of doodlessuggests you aren’t listening very closely to the speaker.

1.2.3. When to Not Listen

Although active listening is a useful skill to employ in most circumstances,you will no doubt discover times when it is most appropriate for you to notlisten, but rather to respond in a more direct manner. For example, activelistening is inappropriate when a speaker is verbally abusive or is out oftouch with reality. Or a speaker may monopolize a conversation in order toprevent you from expressing your ideas or to avoid discussing an issue thatthey are uncomfortable addressing.

In these sorts of circumstances, we recommend that you be assertive withthe speaker by pointing out that they are acting inappropriately and that youwill not continue the conversation unless you are treated with respect. In ex-treme cases, you may even find it necessary to walk away after stating thatyou are only willing to continue the conversation once the speaker hascalmed down.

21


1.3. Team DynamicsEffective teams do not just happen; they require a substantial commitment oftime and energy on the part of all members in order to fully reach their po-tential. In addition to its members having a sound foundation in listeningskills, several other characteristics are typical of effective teams:

• The team shares goals that have been clearly articulated;• Team members frequently interact;• Team members share the decision making power (although often, but

not always, a tacit team leader exists);• Tasks are equitably divided;• The team shares the responsibility for both their mistakes and their

successes;• The free expression of opinions, conflicting perspectives, and con-

structive criticism is always encouraged.

If you want to increase the efficiency and effectiveness of your team, thenyou must learn how to encourage the development of these characteristicswithin your team. The remainder of this section details several ways inwhich you can go about actively developing the characteristics typical of ef-fective teams.

1.3.1. Articulating Goals

When a team first gets together, some time should be spent discussing notonly the general goals of the team, but also the specific personal goals of theteam members. For example, the goals for an engineering project coursecould include such professional development issues as mastering the designprocess and producing effective project documentation. Further, they mightalso include dealing with social issues such as assisting the disabled orfellow students. Individual goals for such a course might include such thingsas developing leadership skills, confidence in public speaking, learning toprogram in C++, etc.

Nor is this need to articulate both professional and personal goals restrictedto the school environment. In the work environment, team members willgenerally establish goals that contribute to the completion of the task whilealso allowing team members to broaden their management and technicalskills. Thus, some team members might be asked to take workshops in man-agement skills in order to increase the value of the team members to theteam and the company.

Once the goals have been articulated by the team members, the team shouldthen consider how to go about achieving these goals. For example, if one ofthe team members wants to develop their confidence with public speaking,then the team might allow that person to undertake any presentations whichare required. In other words, teams should not necessarily divide the tasksaccording to their existing strengths; overall, the team’s strength will be en-


22

hanced by enabling each team member to develop a skill with which theymay lack proficiency.

The establishment of these goals is an important first step in the develop-ment of a team. And teams, like individuals, go through a series of stages asthey evolve. Tuckman (1965) has labelled those stages as forming, storming,norming, performing, and adjourning.1

In the forming stage, team members are often somewhat anxious as they donot yet know the other team members and their roles may be somewhat am-biguous. The storming stage is typified by conflicts over procedural issuesand by misunderstandings or misinterpretations of other team member’s be-havior. In the norming stage, a team grows increasingly cohesive and indi-vidual roles as well as team standards become well defined. During the per-forming stage, the team begins to achieve its goals and the performance ofteam members is emphasized. Finally, the adjourning phase is characterizedby the completion of the tasks and the end of the roles assumed by the teammembers. Table 1 outlines the stages of team development as well as themajor processes and characteristics of the stages.

Table 1: Stages in Team Development2

Stage Major Processes Characteristics1. Forming (Orientation) • Exchange of information

• Increased interdependency• Task exploration• Identification of commonalities

• Tentative interactions• Polite Discourse• Ambiguity• Self-discourse

2. Storming (Conflict) • Disagreement over procedures• Expression of dissatisfaction• Emotional responses• Resistance

• Criticism of ideas• Poor Attendance• Hostility• Polarization & coalition

forming3. Norming (Cohesion) • Growth of cohesiveness & unity

• Establishment of roles, stan-dards, & relationships

• Agreement on procedures• Reduction in role ambi-

guity• Increased “we-feeling”

4. Performing (Performance) • Goal achievement• High task orientation• Emphasis on production & per-

formance

• Decision making• Problem solving• Mutual cooperation

5. Adjourning (Dissolution) • Termination of roles• Completion of tasks• Reduction of dependency

• Disintegration & with-drawal

• Increasing independence• Regret

1 Cited in Engineering Core Workbook for Active Learning, Team Training, and Assessment, Barry

McNeill and Lynn Bellamy, College of Engineering and Applied Sciences, Arizona StateUniversity, 1994.

2 Excerpted from Engineering Core Workbook for Active Learning, Team Training, andAssessment, Barry McNeill and Lynn Bellamy, College of Engineering and AppliedSciences, Arizona State University, 1994.

23


1.3.2. Team Interaction

The most successful teams interact frequently while working on a project.Usually, teams schedule regular face-to-face meetings to plan how they willmeet their goals, to monitor progress toward those goals and to resolve out-standing issues. But such formal meetings are not the only way that teammembers interact. When working on small projects, often the team membersare working in close proximity and see each other on a daily basis. Whenworking on larger projects, team members often stay in touch with eachother via e-mail or over the phone.

Beyond these professional meetings, the members of a team may gettogether socially, perhaps for lunch or after work. Teams with a significantsocial component generally tend to work together much more effectivelythan teams with strictly professional relationships. However, the degree towhich a team socializes is typically dependent upon the size of the team. Alarge team may find it difficult to get everyone together to socialize, while avery small team may find it possible to combine both social and professionalactivities.

Effective meetings are a very important component of team interaction. Un-fortunately, many meetings fail to achieve their goals because they are eitherpoorly organized or poorly run. The following points are some that youshould consider when running meetings.

• Prepare and circulate a detailed agenda in advance of meetings;• Set a timeline for the meeting;• Keep the discussion focused and moving;• Ensure that no one dominates the meeting and that everyone is

heard;• Keep minutes for the meeting;• Evaluate the effectiveness of the meeting;• Set the time and agenda for the next meeting.

1.3.3. Team Roles and Leadership

Within teams, people typically fulfill a range of roles, both formal and infor-mal. In general, these roles can be divided into 2 general categories: task-oriented roles and socially-oriented roles. Task-oriented roles include assignedroles such as team leader (who ensures the overall goals of the team are met),recorder (who keeps minutes of meetings, etc.), and devil’s advocate (who takesthe opposite perspective to the team’s usual view). In addition to those sortsof organizational roles, various team members may fulfill roles related totheir expertise (budget manager, marketing specialist, documentation specialist,etc.).

Socially-oriented roles are typically not assigned to specific individuals, butare instead assumed by various team members (often as a function of theirpersonality). Although not formally assigned (and generally not officially


24

rewarded), socially-oriented roles can be essential to the smooth functioningof a team. These roles include such things as mediator (who helps to resolvedisputes among team members), facilitator (who encourages other teammembers to participate), comic (who lightens things up through humor), andstandard setter (who expresses the standards and expectations of the team).

In addition to these positive social roles, teams may occasionally find thatthey need to deal with problem members such as dominator (who assertspower and manipulates the team), aggressor (who continually disapproves ofteam decisions), and attention seeker (who constantly draws attention to himor her self). Obviously, these sorts of socially destructive roles can have anegative impact upon the effectiveness of the team and, when extreme innature, may require that the team leader or team sponsor take some sort ofaction. In some cases, this action may simply involve discussing the matterwith the problem member in order to resolve the issue, while in other cir-cumstances, the problem member may need to be removed from the team.

Although many of the roles mentioned above can help a team function opti-mally, effective team leadership is often the critical factor in determining thesuccess of a project team or collaborative writing team. Although some smallteams function quite effectively without formal leadership, in circumstanceswhere efficiency is a major concern, or where the team is larger than 4 or 5people, a formally designated team leader is often needed. The leader is re-sponsible for ensuring that the overall goals of the team are met in terms ofcompleting the various tasks involved in the project.

When a leader is formally chosen for a team, care must be exercised in con-sidering what traits are typical of an effective manager. The most strong-willed individual is not necessarily the best choice for a leader; indeed, in ateam with several strong-willed individuals, the choice of one of them canlead to a power struggle, increased conflict, and in extreme cases, the col-lapse of the team. Effective leadership, particularly in small teams, is gener-ally democratic in nature. Some of the characteristics which typify effectiveleaders are as follows:

• Manage their time effectively;• Recognize the limitations of their authority and expertise;• Delegate tasks effectively and fairly;• Are flexible in their approaches to problem solving;• Consult frequently with other team members about issues of concern;• Communicate effectively (i.e., more time listening than talking);• Keep the team focused upon the tasks at hand (i.e., encourage team

members to work toward their personal and team goals);• Encourage the expression of conflicting opinions and alternative

viewpoints;• Provide honest and specific feedback about individual and team per-

formance;• Resolve conflicts between team members effectively and fairly;• Make decisions effectively (i.e., fairly and in a timely manner).

25


To a significant degree, effective leadership is also based upon expertise.Thus someone with a background in project management may be the overallproject manager, someone with expertise in documentation may be thewriting team leader, while someone with experience in engineering designmay lead the design team. This sort of task orientation to leadership roles is,of course, the model most frequently applied in industry. If small teams en-counter difficulty in choosing an overall project manager, leadership may bedelegated on the basis of task expertise or, in some circumstances, the leadermay be designated for a specific period, after which time a new leader ischosen.

1.3.4. Division of Labor

In order to minimize conflicts and increase the efficiency of team, the workmust be divided equitably among the team members. Overburdening oneindividual will quickly lead to resentment and conflict. In addition, when as-signing tasks to various team members, it is important that the teamconsider not only the quantity of work to be undertaken by an individual, butalso the nature of the work.

When working in a collaborative writing team, for example, editing a docu-ment is rarely as interesting as drafting the document. If someone is consis-tently assigned the task of editing, they are liable to quickly become bored(and thus ineffective). A better idea is to rotate team members through boththe less challenging tasks and the more interesting ones.

1.3.5. Team Responsibility

When things don’t work out quite the way we expected them to (i.e., a par-ticular design flops), we often tend to blame it on some external factor. Occa-sionally, however, the members of a team will choose to blame the problemon a particular team member. Although exploring the origins and conse-quences of the problem is necessary in order to prevent a recurrence of theproblem, you should generally avoid placing the blame for a particularproblem on any one team member.

Scapegoating a team member is one of the fastest ways to generate destructiveconflict within a team. Most problems that a team encounters result from ateam decision or dynamic and should be accepted as a team responsibility.The goal should not be to lay blame but rather to determine the nature of theproblem, how to correct it, and how to prevent a recurrence. Similarly, mostsuccesses are the result of teamwork and should not be attributed to theabilities of a single individual.


26

1.3.6. Team Conflicts

Conflict is inevitable when working as part of a team, and one of the keys tohow successfully a team meets its goals is dependent upon how the teamdeals with conflict. Indeed, conflict should not necessarily be viewed asnegative. Conflict is positive insofar as it indicates a problem and thus allowsthe team to recognize it and to start working on a solution. Further, conflictcan prove constructive when it forces us to explore alternatives that wemight otherwise ignore, so be sure to encourage the free expression of opin-ions, conflicting perspectives, and criticism (if constructive).

But remember that excessive conflict can impair the ability of a team toachieve its goals. A balance is required. In order to help you learn to achievethat balance when working as part of a team, the following sections providea model for dispute resolution as well as some information about groupthink(the complete absence of disagreement in a team).

1.3.6.1. Dispute Resolution

The following points summarize the factors which underlie the productiveresolution of disputes when working in a team setting. If these principles arenot accepted by all individuals involved in the dispute, the dispute willlikely require the intervention of a third party to resolve it. An effective teamwill demonstrate the following:

• A willingness to communicate in an open and honest fashion in orderto accurately define the problem;

• A recognition that the interests of all parties are legitimate;• An understanding of the need to find a solution which addresses eve-

ryone’s concerns;• Sensitivity to common interests and a desire to minimize differences;• An effort to limit rather than expand the scope of the conflict;• An attempt to minimize defensiveness by focusing on the problem

rather than personalities;• A commitment to finding a solution that is agreeable to everyone.

The following six stage model provides a useful method for resolving thedisputes you will encounter when working as part of a team.3 You mightcommit this model to memory because you may well find it useful in yourcareer.

1. Fully and clearly identify the problem to be resolved.a) Describe all sides to the dispute.b) Listen carefully to all sides.c) Ensure everyone accepts the definition of the problem.

3 Adapted from Leader Effectiveness Training by Thomas Gordon, New York, NY: Bantam

Books, 1980.

27


2. Generate alternative solutions to the problems.3. Evaluate the alternative solutions.4. Ensure that all members accept decisions.5. Implement the solution to the problem.6. Set a target date to evaluate the effectiveness of the solution.

1.3.6.2. Groupthink

As mentioned earlier, some conflict is useful in terms of helping a team toevaluate alternative approaches to a problem. In fact, the total absence ofconflict may signal that your team is suffering from groupthink.4 Groupthinkresults when a team becomes so cohesive that the desire to maintain loyalty,unity, and agreement prevents critical thinking and open inquiry. Thisproblem is particularly common among small teams working intensively to-ward a specific goal. Some of the symptoms of groupthink are outlined inTable 2.

Table 2: Symptoms of Groupthink

Invulnerability Group members become convinced that what they are doinghas no risks. They become overoptimistic and take excessiverisks.

Rationalization The members of the group collectively construct rationaliza-tions which discount negative feedback or discrepant informa-tion.

Morality The ethical consequences of their decisions are discounted bythe group members.

Stereotypes Competition for the leadership of the group is viewed as nega-tive.

Pressure Group members are pressured to conform to the norms of thegroup.

Censorship Deviation from the group consensus is not permitted. Doubtsor concerns about group goals and approaches to problems areminimized.

Unanimity Group members support the majority position. Minority view-points are not given a fair hearing.

Protectiveness Some group members may assume the role of protecting theleader and other team members from negative informationwhich may adversely affect the confidence of the group in itsapproach.

One way to prevent groupthink is by encouraging at least one team memberto actively take on the role of devil’s advocate. Yet perhaps the best way toprevent groupthink is by positively valuing and encouraging the expressionof each person’s individuality.

4 The information about groupthink has been adapted from Irving Janis’ article,

“Groupthink”, in Psychology Today, November, 1971, pp. 71-89.


28

1.4. Writing as Part of a TeamAs we mentioned at the beginning of this chapter, throughout your career asan engineer, you can expect to spend a significant amount of time workingand writing as part of a team. In this section, we provide some basic infor-mation about team writing processes and suggest strategies you may finduseful. But first, a few general comments about collaborative writing may beuseful.

One of the major complaints many people have when asked to write docu-ments collaboratively is that team writing is time consuming and frustratingbecause different people have different ideas concerning how to organize adocument, what is important, how quickly a draft should be completed,what words to use, what counts as good style, how to punctuate, and so on.However, the benefits gained by working in a collaborative writing team canbe substantial:

• Improved interpersonal skills;• Increased confidence in your ability to work in teams;• Increased leadership potential;• A greater appreciation of the value of individual differences;• Greater creativity;• Better documents;• A better understanding of your composing process and of how others

compose;• A better understanding of how you and others solve problems;• Lasting friendships.

As we said at the beginning of this chapter, working in a team allows you toimprove your interpersonal skills. And improvement increases both confi-dence and leadership ability. Because engineers frequently work on teamswith people from other fields and disciplines who have diverse backgroundsand experiences, tolerating different perspectives and approaches may be es-sential to your own success. Engaging in collaborative writing, or any othercollaborative activity, can help you develop this appreciation of differentways of thinking and approaching problems.

Furthermore, developing a true appreciation of diversity and encouragingthe full participation of those with different perspectives greatly increasesthe potential for creative and innovative solutions to all sorts of problems.For example, when all ideas, however crazy or eccentric they may firstappear, are carefully considered, the teams’ creative potential is greatlyincreased. When a team functions well, the increased brain power, diversity,and creativity can lead to results far beyond those possible by any onemember of the team.

Of course, this increased ability also applies to documents; when a collabo-rative writing team functions well, the resulting document can be much su-perior to that produced by any one member. At the same time, collaborationslows things down which encourages certain kinds of understanding. For

29


example, the give and take necessary to achieve consensus allows many op-portunities to compare our approaches and processes with those of others, toquestion our own assumptions, and to become more aware of the potentialrange of ways of solving problems, of reaching decisions, and of composinga document. And by recognizing these differences, we can enhance our criti-cal thinking and problem solving abilities while increasing the potentialrange and flexibility of our approaches.

Collaborating on a project or writing assignment can also lead to lastingfriendships. Working closely with people while striving for consensus is anexcellent way to get to know people and their abilities. And the friendshipsyou make while a student can have a direct bearing on your future career. Inengineering, as in many other fields, job opportunities are as likely todepend upon knowing someone in a company as on an impressive résumé.

If someone can vouch for your abilities and confirm your suitability for a po-sition, then your chances of gaining the position are greatly improved. In thehigh technology fields that we are most familiar with, engineers tend tochange jobs relatively frequently. And a significant number gain employ-ment or move into better positions in companies where they have friends.Keep this advantage in mind when involved in team projects.

1.4.1. When to Use a Team Writing Strategy

While a student, you may not have much control over the situations inwhich you write collaboratively. However, some situations are particularlywell suited to collaborative writing and worth keeping in mind. Considerwriting collaboratively when you need to accomplish one of the followinggoals:

• Producing a large document in a limited time;• Producing a document requiring a broad range of expertise;• Resolving divergent or opposing viewpoints;• Clarifying a team position or shared approach.

While a short document can generally be more quickly produced by an indi-vidual than a team, longer documents are often well suited to a collaborativeprocess in which a number of individuals draft sections. But even documentsof a moderate length are best written collaboratively when no one person hasthe necessary expertise or when the object of the document is to reach a con-sensus. In fact, collaborative writing is sometimes used specifically for thepurpose of building a cohesive team by creating a situation in which a groupof people must achieve agreement in order to accomplish the task at hand.

Collaborative writing is also useful when viewpoints on how to address aproblem or issue must be resolved in order to complete a project or docu-ment. By writing collaboratively, two or three individuals with differingopinions can sometimes work through their objections and reach a compro-mise that all can accept. More frequently, collaborative writing is a usefulmeans of clarifying and refining an issue, approach, or position. But keep in


30

mind that collaborative writing, like other forms of collaboration, requiresgood listening skills and attention to team dynamics so that all members willparticipate by pointing to possible problems, raising objections, offering sug-gestions, negotiating wording, and otherwise contributing to the team effort.

1.4.2. How the Collaborative Writing Process Operates

The term “collaborative writing” applies to a number of situations in whichtwo or more people are involved in some aspect of the composing process.At one extreme, writers produce a document by working together to plan,draft, revise, and edit a document. We call this approach Team-composing.You are unlikely to engage in this approach on the job very often, because itis generally very time consuming. However, it can prove effective when thepiece is short and two (or very few) people with similar ideas are committedto a shared goal – especially when one is a good writer and the other has sig-nificant contributions to make in terms of ideas.

At the other extreme, one writer drafts and others revise, edit, and perhapseven format the document. You may encounter this Single-file approach onthe job, but we discourage you from using it when you can avoid doing so.As the name suggests, this approach provides little, or no, opportunity forteam interaction. Another drawback is that the person who drafts the docu-ment often has little, if any, control over the sorts of changes made by who-ever revises. This lack of control can adversely affect the drafter’s motivationto do their best work.

A Combined approach is better suited to developing interpersonal skills whileintroducing you to the kind of collaborative writing you will encounter mostoften on the job. The most common variation of this approach involves col-laborating with your team members to plan and revise, but drafting aportion of the document on your own. Note that on occasion, someparticularly important section or sections may be collaboratively drafted, butindividual drafting is the norm. The following sections address issuesrelating to this Combined approach.

1.4.3. Collaborative Planning

The planning process for a document, like that for a project, is generally ini-tiated with a brainstorming session to determine how to deal with variousaspects of the writing task. To keep as many ideas and points visible to theteam as possible, consider working in a room with a large black or whiteboard, or using a flip chart and taping finished sheets to the wall, or decideupon some other technique that serves the same purpose. Also consider ap-pointing someone to write down ideas, and someone else to keep notes onthe meeting so the team has a record of points to remember, a record ofscheduling decisions, a list of questions that need answering, and so on.

Practicing engineers sometimes begin these brainstorming sessions byidentifying members familiar with the type of document being written and

31


calling upon them to lead the session. If the document form is new to theteam, they may begin by reviewing existing documents of the same type. Inmany cases, they will work from templates provided by the company.

While familiarity with the type of document required is important, two es-sential steps are sometimes omitted from the collaborative planning process:

• Establishing the objectives the document must fulfill to be successful;• Analyzing the readers for whom the document is intended and de-

ciding upon an effective approach.

In Module 1, we discussed the importance of identifying your objectives andanalyzing your audience and suggested strategies for doing so. The impor-tant things to remember at this point is that the team must have a clear ideaof what they hope to achieve and of what their readers want. Some timeshould be devoted to clarifying objectives and they should be written downin a sentence or in point form and distributed to all members of the team sothey can refer to them while drafting and during future meetings.

The team should also devote part of their first brainstorming session to ana-lyzing their readers to determine what the team collectively knows abouttheir readers, what information they think their readers want, what concernsreaders may have, what will sell, and so on. In fact, the audience analysismay help clarify the goal, and so the objectives should be revisited after theaudience analysis is completed. (At this point, the team may want to decideif the meeting should continue or another needs scheduling.)

Once the objectives are clarified, the audience analyzed, and everyone is fa-miliar with the type of document they will be writing, the team should moveon to the following steps:

• Deciding upon content, organization, graphics, format, and style;• Generating a topic outline for the document.

Discussions of graphics, format, and style were discussed at some length inModule 1. However, on the job, many issues relating to style, format, andgraphics may be dictated by a company template or style. And in college,you may be given precise instructions for or an example of the kind ofdocument required. If such guidance is not available, you need to decidewhat you want your document to look like. And you may want to find anappropriate model to guide formatting decisions.

Begin brainstorming about what topics to include and how to organize them,how to break them into sections, what sort of graphics would be useful andwhere, what general formatting conventions you plan to adopt, and anyelements of style you can think of. Note, however, that you can deal withstyle at a later point in the planning process. Consider putting off a discus-sion of style if you do not have an example of the kind of document you areto write and/or you determine that a discussion of style will waste time andtake your session off-track at this stage. If necessary, the team can assign oneperson to act as editor and stylist.


32

Once you have a clear idea of the content and general organization of yourdocument, consider the relative importance of your subjects and how thesubjects relate to one another. Lay out general sections for everyone to see,add specific topics under the appropriate headings, indicating which onesare main topics and what more specific ones fall under them. If you are for-tunate enough to have access to a computer during your session, considerhaving someone enter the resulting outline in the computer so that you caneasily move items and quickly produce a copy of the completed topic outlinefor all members of the team.

Once this outline is completed, you can turn your attention to determiningwhat roles each member of the team will play, what portion of the work eachwill do, and a schedule for completing the various tasks. The following stepsshould be included in this portion of the planning process:

• Deciding which approach you will use for drafting and revising thedocument;

• If possible, agreeing upon a common operating system, word proces-sor, and graphics program;

• Assigning individual tasks as required• Setting the deadlines which must be met in order to complete the

document in time to meet the overall project deadlines.

As indicated earlier in this section, the normal procedure is for individuals todraft sections. However, the team may decide to work together on a particu-lar section. And occasionally, two individuals may want to write togetherbecause they find it easier and faster than writing alone. While this prefer-ence is not common, some writing partners work very well this way.

As well as determining who will write which sections, consider how thevarious sections will be merged and how you will produce or import graph-ics. If the equipment and software available to the team is varied, then con-sider how you will produce the final draft before you begin work. Andconsider how much work you will create for particular team members. Alsodetermine if any research is required and who will be responsible for whataspects. And keep these tasks in mind when balancing the work load amongteam members.

Your choice of an approach for revising will also play a role in determiningeach member’s responsibilities. In general, everyone should participate in re-vising. That is, everyone should read the completed draft and prepare com-ments and questions for a team meeting. After everyone’s concerns and sug-gestions are presented and discussed, all members may decide that they willeach revise their own sections. Note, however, that one person should be ap-pointed to undertake a further revision so that the style of the final draft willbe consistent throughout. Alternatively, after the team meets to discuss revi-sions, one person (rather than individual members) could take responsibilityfor revising the entire draft. In either case, all members of the team shouldread the revised draft, especially when all members share responsibility forthe final product.

33


Before the team moves on to their individual tasks, take time for the follow-ing steps:

• Review the topical outline to ensure that all requirements in terms ofcontent have been met and the topics are logically ordered;

• Ensure that everyone is clear on and agrees to the approach, task di-vision, and schedule.

Taking time to recap and clarify agreements during the planning process en-sures that no points are missed and that everyone agrees. Much time andfrustration may be avoided later on by taking the few extra minutes requiredfor this kind of review.

At some point in the planning process, the team should also discuss man-agement issues. While some teams function quite well without an officialteam leader, others find clear lines of authority make tasks easier to com-plete. And so, take the time to consider whether your team would benefitfrom a project manager, a dispute arbiter, a writing editor, or some otherform of leadership.

Note that further planning sessions may be required once certain tasks arecompleted. In fact, regularly scheduled meeting are often useful to discussprogress and to help ensure that everyone is working to meet theirdeadlines. Also note that the suggestions for planning offered above are notthe only viable approaches; teams often develop their own strategies orvariations to suit their needs.

1.4.4. Collaborative Revision

Once the initial drafting is completed, the team meets to begin the revisionprocess. As discussed in the previous chapter, revising is handled in a top-down manner, concentrating first on content and organization at the docu-ment, section, subsection, and paragraph levels, and then on sentence struc-ture, style, grammar, and punctuation. And so, revise in several sweeps orstages, focusing first on content and organization and then on style, correct-ness, and formatting details.

If the team has planned well, revisions to content and organization should befairly straight forward. The more detailed revision for style, word choice,punctuation, and even grammar tend to be more time consuming and con-tentious. One way to avoid getting bogged down in this part of the process isto appoint an editor who listens to everyone’s comments, but is trusted tochoose the best solution and given responsibility for achieving consistency instyle, punctuation, and so on.In some cases, you may also want to appoint members to take on the role ofthe intended audience and responsibility for suggesting points for revisionbased on what the team has determined about the audience’s knowledge ofthe subject, concerns, expectations, etc. This special attention to audience canbe the key to producing a successful document.


34

Before we end our discussion of collaborative writing, we turn your attentionto another form of collaborative revision that is commonly employed in thework place: document review. Note that much of the advice offered in the fol-lowing discussion of document review is worth keeping in mind for teamrevision.

1.4.4.1. Document Review

In the work place, document reviews are often undertaken by supervisorswho have the authority to demand changes. In some cases, supervisors willdiscuss their concerns and suggestions with the writer and negotiatechanges. In other cases, supervisors may impose changes and the writermust adjust content and style to accommodate the supervisor’s preferences.However, document reviews can also be collaborative when peers revieweach other’s work. We therefore focus on advice for providing suchcollaborative peer reviews.

1.4.4.2. Peer Review

As a writer, you should approach a document review as an opportunity foruseful feedback. Either meet with the reviewer or write out a list of thingsyou want considered. For instance, if you are not satisfied with a section orwonder if the tone is appropriate, tell the reviewer your concerns so that heor she will pay particular attention to those aspects of the document. Youshould also explain any features of your document that are unusual or po-tentially controversial so that the reviewer understands your choices. Alsostate the purpose of your document and provide relevant information aboutyour intended readers.

As a reviewer, you should keep in mind that heavily negative criticism tendsnot to help the writer. The following guidelines suggest ways of ensuringthat your provide constructive criticism.

Familiarize yourself with the writer’s audience and purpose. If the writer hasnot provided you with a clear sense of the context for their document, ask forclarification. And keep in mind that you are expected to evaluate the docu-ment as if you were the intended reader. Your comments should also be di-rected toward the writer’s specified purpose. If appropriate, comment on thefit between the audience and purpose and on whether or not the result thewriter hopes to accomplish is clear.

However, do not begin making comments too quickly. Read the document atleast twice. Read the document through the first time simply to clarify thegist of the argument and its relevance for the target audience. Your goal onfirst reading is to gain a general sense of the content. During the secondreading, you can either make marginal notes on the document or organizeyou comments on a separate sheet of paper. If you make marginal notes,

35


avoid using a red pen; documents that look like they are bleeding are oftenmore discouraging than helpful to the writer.

Unless you have been asked to do so, do not respond to grammar and style.However, point to any wording or sentences you find unclear or ambiguous.When responding to issues of content, audience, or purpose, avoid tellingthe writer what to do. That is, rather than writing, “You must address theconcerns or fears of your readers,” consider a statement along the lines of “If Iwere your reader, I would be concerned about X.”

Of course, you can make suggestions, but be sure to back them up with rea-sons to explain your approach might work better. For example, “If you admit-ted that X is a valid point, you could then argue Y.” And when responding to thecontent of the document, phase your criticisms as questions rather than asstatements. For example, “This is wrong!” is much less effective than “Are yousure you have your facts right?”

Make a special effort to respond to the positive elements of the document aswell as to the negative ones. Writers need to know both what works andwhat doesn’t. However, be honest with your comments. If you see a prob-lem, do not avoid telling the writer simply to avoid hurting his or her feel-ings. But at the same time, take a moment to consider whether or not you areacknowledging a problem or pointing out the way you would have donesomething.

Writers rarely appreciate having someone else’s style imposed upon theirwriting, as you will likely learn when you have a supervisor who imposeshis or her style on your writing. Through team revision sessions, you shouldgain a better idea of the variety of ways in which writer’s express themselvesand learn a certain amount of tolerance and gain a better sense of when com-promise is appropriate.

As a final point, we suggest that you seek opportunities to review other peo-ple’s writing. As anyone who spends a significant time reading and re-sponding to other writers knows, reviewing and commenting on other peo-ple’s documents is a very effective way to improve your own writing.

¦


36

2. Chapter Two: Project Documentation


38

39


2.1. Project Documents

[ Introduction[ Creative Thinking[ Project Phases & Documentation[ Proposals[ Functional Specifications[ Design Specifications[ Users & Technical Manuals[ Progress Reports

2.1.1. Introduction

RECENT CASE STUDY INDICATES that engineers spend about 10-15% oftheir time engaged in producing documents when working on aproject. In other contexts (i.e., where people are engaged in writing

proposals or analytic reports), engineers may spend upwards of 50% of theirtime writing. Consequently, the time devoted to writing can amount to acost of hundreds of thousands of dollars to a company. For this reason, youmust learn to produce the required documents in the most efficient mannerpossible. Even a 10% increase in your efficiency with writing can save yourcompany tens of thousands of dollars. With smaller companies, this sort ofsaving can mean the difference between financial success or failure on anygiven project.5

Yet beyond the direct savings which can accrue from increased efficiency inproducing documents, there can also be indirect, but nevertheless tangible,benefits. For example, a company which manufactures a product accompa-nied by an effective User’s Manual is far more likely to generate repeat busi-ness than a company which produces a poor quality manual. In many cases,the value of a device or software package is determined by how well an op-erator can use it. If the product is sound and competitively priced, the differ-ence between success or failure may lie in the documentation.

5 For example, a 1990 case presented by the SFU Applied Sciences Program (Continuing

Studies) of estimates for the design and production of a prototype optical tape recorder byCREO Electronics Corporation indicated that approximately 11% of the total engineeringtime was budgeted for documentation. This 11% was equal to about 3.3 person years oftime, resulting in a total labor cost exceeding $120,000 devoted solely to the task ofproducing project documents. Note that these figures only relate to the time spent onformal project documentation and do not include the time spent writing letters, memos,etc.

A


40

When undertaking a specific project for a client, you must very accuratelyunderstand what the client wants. Misunderstandings between the engi-neering team and their client are an all too easy way of increasing the timeand costs required for a project. The costs can become prohibitive if misun-derstandings require the team to rework initial designs once work on theproject is well underway. Documents such as the RRFP (Responding to a Re-quest for Proposal) and the Functional Specifications are aimed at preciselydefining the needs of the clients.

At various points in your career, you will doubtless find you are engaged ina project which requires you not only to design hardware and/or software,but also to help produce the documentation required to support that project.In order to ensure you master this process, project teams for ENSC 305 arerequired to generate the range of documents usually required for engineer-ing projects. These project documents include, but are not restricted to, aProposal, Functional Specifications, Design Specifications, Progress Reports(usually several), and, in some cases, a User’s Manual. This chapter outlinesthe format and content requirements for some of those project documents.

You are advised to start conceiving of project documents as devices whichmust in themselves be designed.6 Project documentation should not beviewed as some unpleasant and unnecessary adjunct to the design and pro-duction of the hardware and/or software. The production of project docu-mentation is integral to the design process itself. You are expected to applythe same principles of design to the project documentation as you apply tothe production of the hardware/software.

In other words, the documentation should be engineered. At heart, this meansthat you must consider project documentation in terms of its functionalityfor the reader: “Does the document function in a way that meets the client’srequirements?”

As we evaluate the documents that you produce for the project courses, wewill consider the following issues:

• Is the document organized appropriately?• Does the document provide a clear and concise concept description

that is written in lay person’s terms?• Does the document provide all the information needed (including

risk analysis)?• Is the document written at an appropriate level of complexity for the

target audience?• Is the document formatted and styled in a fashion that assists the

reader’s comprehension of the information it contains?• Is the document appropriately persuasive and/or informative?• Is the document of professional quality in terms of form and content.

6 The conception of documents as devices which must be engineered has been derived from

Edmond H. Weiss' text, How to Write a Usable User Manual (Philadelphia, PA: ISI Press,1985).

41


2.1.1.1. Audience

To some degree, the nature of your audience will vary depending upon thenature of the project as well as the specific document upon which you areworking. For example, if you are designing and producing a device whichwill be used by first year students or the general public, then you wouldwrite the User’s Manual or Service Manual at a level of complexity appropri-ate for their background.

The Technical Manual for such a device, however, would be written for anaudience with a level of expertise equivalent to your own. The RRFP andFunctional Specifications on the other hand, should be specifically aimed atthe client requesting you build the device (note that the Design Specificationsare usually an internal document and thus are not usually aimed at the cli-ent). Often, this client will be an ENSC faculty member although, in somecases, the client may be a private company or government agency.

As well as designing some documents for a specific audience, you are alsoexpected to consider carefully the problem of multiple audiences. The RRFP,for example, is often aimed at three different audiences: an accountant, anengineer, and an administrative executive. Writing an RRFP for this kind ofmultiple audience is far more difficult than writing for a single audience.

Different sections of the RRFP must be specifically designed for each audi-ence simply because each individual has different interests and areas of ex-pertise. And each individual is persuaded in different ways (i.e., cost effec-tiveness, technical feasibility, delivery date). Although generally you will bewriting your RRFP for one individual, the faculty client, you are expected todesign the document as if you were in fact writing it for multiple audiences.

Finally, you are expected to remain in close contact with your client (or in-structor, as the case may be). Aside from the written progress reports youare expected to provide your client, you must meet informally with themoften enough to keep them apprised of your progress. Weekly or bi-weeklymeetings are recommended.

Past experience has demonstrated that those teams which maintain closecontact with the client produce the highest quality devices and documents.Those teams which fail to communicate effectively with their client haveproduced devices which do not meet the needs of the client, have missed de-livery dates, and have experienced cost over-runs. Failures in device func-tionality or meeting delivery dates impacts upon your grade for the projectcourses (and cost over-runs come out of your pocket). In the work world,these sorts of failures may result in the loss of your job.


42

2.1.1.2. Purpose

As with considerations of audience, the purpose for project documentationvaries depending upon what specific document is being produced. For ex-ample, the RRFP is primarily persuasive in purpose, (although it also servesimportant informative purposes). Because many projects are tendered on acompetitive basis, you must persuade the prospective client that you possesssufficient expertise to design a device that will meet their needs, that will becost effective, and that will be delivered on time. The User’s and TechnicalManuals, on the other hand, are primarily informative (although informationis, to some degree, also persuasive). Thus, you want to clearly explain howto use or repair/modify the device.

Beyond these two rather obvious purposes, project documentation alsoserves other functions. Overall, the documentation serves as a record of thedesign process, what was done and how, as well as why certain decisionswere made. Thus, in some circumstances, project documentation can serveimportant legal functions (i.e., in the event of a product liability lawsuit).

And further, some of the project documents serve a very useful generativepurpose. The Functional Specification is critical in completely and accuratelydefining what the hardware/software must do for the client. It also providesthe legal basis for determining if the agreed upon job has, in fact, been com-pleted. Moreover, should you ever need to prepare a patent description, awell-written Functional Specification makes this a relatively simple task.

The Design Specification, on the other hand, is critical in defining preciselyhow you will implement the required functions. As you produce these twodocuments, you will quickly discover that the act of writing them for the cli-ent will generate questions that help you clarify design problems and alter-natives. In other words, project documents are not simply written to informor to record; they are essential to creating your design. As mentioned earlier,project documentation is integral to the design process.

2.1.1.3. Format

Note that this section provides only very general information about format,and instead focuses upon the content and purpose of the various documents.We assume that you will read and follow the more detailed format guide-lines provided in the next chapter. You are also expected to review some ofthe samples of project documents which we keep on file. Learning how toproduce these documents is easier if you actually read them than if you onlyread about them. Consequently, you will be provided with samples of thedocuments produced by other design teams in previous semesters.

Please treat these sample documents with respect. They are the originalsand must be returned in good condition once you have completed thecourse. Also bear in mind that all of these sample documents possess arange of flaws, so do not simply copy their style or format.

43


2.1.1.4. Document Sections

In general, the following are the sections you are expected to include in mostof the project documents:

• Letter of Transmittal• Title Page• Executive Summary• Table of Contents• List of Figures and Tables• Background or Overview or Introduction• Body of the Document• Conclusions or Recommendations• Glossary (sometimes placed after List of Tables)• Appendices

Note, however, some exceptions to the above organization (most notably, inthe RRFP and the User’s Manual). These exceptions are dealt with in thecomments about the specific sections provided below. Also note that you areexpected to include a letter of transmittal along with all your documents.

2.1.1.4.1. Letter of Transmittal

In the letter of transmittal, you draw the attention of the intended audienceto the contents of the document. It should include the title of the document, astatement of the subject and purpose of the document, and how you can becontacted for further information. Please note that the letter of transmittalshould not be stapled or otherwise bound with the rest of the document; itshould simply be attached with a paper clip. Usually the letter of transmittalis removed from the document by a filing clerk and is filed separately. Seethe section on format guidelines in the next chapter for an appropriate for-mat for the letter of transmittal.

2.1.1.4.2. Title Page

In addition to a title which clearly represents the content and scope of thedocument, also include information about your company (the companyname, the individual to contact, and their position and phone number) thename of the principal reader (as well as their position and company, if ap-propriate), the date of submission and the document revision number. Youmay also include the proposed cost and the signatures of the design team onthe title page of the RRFP. However, do not include these last two items onthe title page of the other documents.


44

2.1.1.4.3. Executive Summary

The executive summary is a one page (maximum) summary of the docu-ment’s substance. Because it is a summary, it should be the last part of thedocument that you write. Although superficially similar to an abstract, theexecutive summary is specifically designed for the non-technical audiencewho has the final authority to approve the project, but who may not read theentire document. You should devote considerable effort to your executivesummary as it serves an important persuasive function; in some sense, it“sells” the project to those who are in a position to approve your project.

This section must be written in plain language (i.e., assume a non-technicalgrade 12 education) and should not refer specifically to the document (i.e., itshould be able to stand as a completely self-contained document). Note thatin the executive summary for the RRFP you must include the proposed costof the project, the proposed timeline, and a brief summary (i.e., two or threesentences) of your company’s qualifications to undertake the project. Alsonote that you do not include an executive summary with the User’s Manual.

2.1.1.4.4. Table of Contents and List of Figures

See Chapter Three for descriptions and examples of the table of contents aswell as the list of figures and tables.

2.1.1.4.5. Background/Overview/Introduction

Depending upon which document you are writing, you include either abackground section, an overview, or an introduction. In the RRFP, you gen-erally include a section detailing the background to the problem and statingthat the document is a proposal outlining a potential solution to the problem(as well as its cost and timeline). In the Functional and Design Specifications,include a section providing a conceptual overview of the system or device(including a system block diagram) and the objectives of the system (i.e., thesystem benefits for the user). In the User’s Manual, provide an introductionexplaining what the hardware/software does and outline the organization ofthe manual, including the typographic conventions used (this outline may bein a separate section entitled “How to Use This Manual”).

2.1.1.4.6. Body of the Document

The content of the body of the document varies extensively from documentto document; consequently, this information is provided in the sectionsabout specific documents which follow this general overview.

45


2.1.1.4.7. Conclusions/Recommendations

In most documents you are expected to include a general summary of the in-formation contained within the body of the document. However, in theRRFP where you are often proposing alternative solutions, you shouldinstead conclude with your recommendations. Ensure that you clearlyexplain your rationale for recommending a particular alternative.

2.1.1.4.8. Glossary

Including a glossary that defines any specialized terms or acronyms withwhich your reader may be unfamiliar is generally necessary in the User’sand Technical Manuals. However, to aid the reader and in the interests ofefficiency, we recommend that you also include a glossary in the Functionaland Design Specifications. If you start compiling your glossary early in thedesign process and then keep adding to it as necessary, you will have lesswork to perform when writing your manuals.

In the project courses, you will discover that you end up doing much of thework in the final two weeks. Usually you are in the final stages of buildingthe hardware, writing and debugging the software, as well as writing theUser’s and Technical Manuals. The more work that you can have doneahead of time, the less pressure you will be under during this critical period.

Note that you have the option of placing your glossaries in the prefatorypages, immediately following the list of tables. This practice is particularlyhelpful if you use a lot of acronyms or specialized terms in the document.

2.1.1.4.9. Appendices

Almost all of the documents contain one or more appendices. In general,these appendices contain narrowly specialized and highly detailed informa-tion such as mathematical proofs, detailed circuit schematics, detailed budg-ets, and any technical information that might create information overload forthe majority of readers. In the RRFP, however, you sometimes include singlepage résumés of the members of the project team. In the User’s Manual, youoften include a trouble-shooting flowchart and a quick reference card asappendices.

2.1.2. A Creative Digression

So what does creativity have to do with technical writing? Certainly, we allthink of creative writing as involving the writing of poetry, stories, and nov-els. But, technical writing? Part of the reason that many may not view techni-cal forms of writing as being especially creative involves a misperceptionthat technical documentation simply reports information previously discov-ered in dispassionate research. Yet such could not be further from the truth.


46

Just as the novelist brings together such things as character, scene, plot, ac-tion, etc. in order to create a story, the engineer brings together science, ma-terials, financing, and marketing, etc. in order to create a device or system. Inorder for any engineering project to be successful, a story must in fact betold. Is the device physically possible? Are the necessary materials available?Can the funds be found to produce it? Will anyone want to purchase and useit? Engineering documentation does not simply report previously discoveredinformation, it actually helps to structure the search for that information.

But unlike the novelist’s story which is created and told through the meansof a book, the engineer’s story is told through a range of documents such asproposals, research reports, requirements, functional, and design specifica-tions. The difference between the novelist and the engineer is not one ofcreativity, but rather of the forms they use to express that creativity. Indeed,even the purposes of the novelist and the engineer are similar: to inform, topersuade – ultimately, to motivate.

Just as the novelist provides information about character and scene, so toothe engineer must inform his or her audience. Just as the engineer must per-suade others to adopt her or his proposal, so too the novelist seeks to per-suade the audience to adopt his or her ideas. And, in both cases, the intent isto motivate the audience to act – usually to change social conditions for thebetter.

Nor should we misperceive that it is possible to undertake an engineeringproject of any significance without its accompanying documentation. Thedevice or system being built is integrated with the documents in very specialways. Without the proposal, the project would not get under way. Withoutthe requirements and functional specifications, the problem would not beclearly defined. Without the design specifications, the device or system couldnot be manufactured. Without the user’s documentation, the device wouldnot get used. The project design process guides the writing as much as thewriting guides the project design process.

Although in some cases, a project you undertake will be defined in fairlynarrow terms, in other cases, you may be provided the opportunity todesign a system or product of you own. While this opportunity providesyou with considerable latitude for your imagination, you may also find thatcoming up with new ideas or new approaches is somewhat overwhelming.

In part, you may encounter this problem because creativity is often describedas an innate ability (i.e., something you are born with) or worse, as arisingfrom some sort of mystical inspiration. Consequently, many people havebeen persuaded that they are not very creative. That perspective is particu-larly unfortunate because your own personal creativity can actually be en-hanced if you are willing to learn to observe the world around yourself withan open mind. Thinking creatively requires a “what if” approach to theworld.

47


2.1.2.1. Problem Posing7

While all engineering schools teach their students how to go about solvingproblems, fewer provide sufficient opportunity for posing problems. By posingproblems, we mean learning to recognize the potential for alternative or newproducts and systems by observing various aspects of the world around usand then asking questions about what is going on. The following providesyou with a method intended to help you think creatively by learning how togo about posing problems to yourself and others.

1. Observe how existing industrial, commercial, or consumer productsand systems work. One trick that some experienced designers use in-volves collecting old, even apparently bizarre, designs for products.Sometimes the old designs failed not because the concepts wereflawed, but simply because the available technology was insufficientto complete the task. For example, swing-wing aircraft were designedprior to World War I, but it wasn’t until 1945 that the technology re-quired to support the design was developed.

2. Analyze the purpose of existing products or systems with an eye tofinding inefficiencies or problems. Can the devices or systems bemade simpler to use or cheaper to produce? Considering the psycho-logical, physiological, environmental, technical, and social processesthat are involved with using and producing the products or systemswill help you recognize problems which need to be resolved.

3. Analyze the nature of the problem by considering whether solvingthe problem is physically possible. Also consider whether or not solv-ing the problem is fiscally possible (i.e., is the product potentially use-ful enough that a market will exist for the product?).

4. Determine how to improve the product or how to resolve or restatethe problem.

5. Consider how to go about developing and marketing the product.

How might you apply this method? Consider, for example, the experience ofa student project team at Simon Fraser University. This team recognized theneed to design a new type of portable heart monitor by observing that thecurrent monitors were a strain to use for people with heart problems becausethey were bulky and heavy. By considering the physiological limitations ofpeople with heart problems, they reasoned that it would make sense tominiaturize the monitors using more modern technology.

Once the group had determined that their proposed solution was physicallyand technically possible, they built a prototype, and then sought funding tofurther develop the idea. And accompanying and guiding this project werean array of documents: initial proposal, functional and design specifications,user’s documentation, formal funding proposal (along with many memos,notes from brainstorming sessions, letters, and meeting minutes).

7 We would like to thank Andrew Rawicz (Simon Fraser University) for his contributions to

the section on problem posing.


48

Not only can this method be used to improve existing products, but with mi-nor modifications, it can also be used to help you generate new products. Ofcourse, in the case of a new product, the key problem involves coming upwith the new idea in the first place. Although by no means easy, you canalso enhance your creativity by utilizing one or more of the followingapproaches to generating ideas.

2.1.2.2. Observing Nature

The natural world around us can be an amazing source of ideas. Observingthe structures and behaviors of various plants, insects, animals, and land-scapes can be a useful way of generating new ideas and alternative ap-proaches to problems. For example, the inventor of Velcro came up with theidea simply by observing how the burrs from certain types of plants adhereto the fur of animals.

Although observing the world around you is no guarantee that you will in-vent the next Velcro, a walk in the woods will at least be a relaxing andpleasant experience. Because creativity generally requires that you berelaxed and relatively stress-free, you are likely to be much more receptive toany ideas that you generate when relaxed. For this reason, meditation issometimes also suggested as a means to enhance creativity.

2.1.2.3. Focused Meditation

Meditation is a strategy that some people find useful for opening themselvesup to ideas. It involves taking a key idea or problem and focusing upon it ina relaxed atmosphere with few distractions. Although providing a completecourse on meditation is beyond the scope of this text and requires consider-able practice, you might try the following method.

Put on some relaxing music, find a comfortable chair (or even lie on thefloor), close your eyes, and breathe slowly and evenly. Relax the muscles inyour body starting with your facial muscles and working down throughyour neck, your torso, and your limbs. Once you are fully relaxed, perhapstry to visualize the ideas that go through your mind as clouds slowlypassing by on a sunny day. Then slowly switch your focus to the particularidea or problem you want to consider. Look at it from different perspectives,just as if it were a cloud slowly floating by. How does it look from the top?From the other side? And if other thoughts and ideas intrude, let themslowly float by, and then return your focus to your topic. After meditating,record any insights or ideas you have had about the topic.

2.1.2.4. Role Playing

Our imaginations are limited by our experiences. To some degree, we canovercome this limitation by seeking out new experiences. Consider, for ex-ample, if you are working with products for the physically disabled. One

49


way to come up with ideas for products would be to intentionally put your-self in situations where some of your senses or your limbs are disabled. Tryto function for a day wearing a blindfold or tie your hands behind your back.

As you will quickly discover, you will want to do certain things which are nolonger possible. Recognizing the problems you confront and then analyzingthem may provide you with a range of new ideas. And if nothing else, youwill walk away from the experience with a very different perspective abouthow challenging it is for the disabled to do the things most of us take forgranted. (Also note that role playing is a very useful approach for testingproducts intended for the disabled.)

2.1.2.5. Free Writing

This strategy is aimed at generating ideas through the medium of writing.Because language and thought are so integral, when we write we often dis-cover or create new insights. Moreover, the following two methods haveother important benefits such as resolving writer’s block or documentingoriginal ideas for things like patent applications.

Free writing is a way to generate ideas by letting your mind freely explore atopic while simultaneously recording those ideas that occur to you. Set your-self a general question about your subject and then find a place in which youwill not be interrupted. Write as much as possible about your topic in a 15 to30 minute period. Pay no attention to your spelling, grammar, or organiza-tion. Avoid revising your writing or censoring what you are writing. Do notstop. If you become stuck, write about whatever comes to mind no matterhow unrelated it may seem. The point is to break through inhibitions and toencourage creativity and imagination. Figure 1 provides a short example offree writing.

OK So I need to write about brainstorming. Usually itsdone in a group but not always sometimes individual.Works best in a group though people feed off each otherscreativity especially if they have different backgrounds –social professional – etc. So how does it work as a group- get people together for a time period ½ to 1 hour- anything goes. don’t want criticism – insane crazyideas are ok- need to ensure nobody gets censored though so need- a group leader to facilitate stuff. should also record- Also good to later sort out ideas by being criticaland further exploring themBut the biggest point is to make sure that there is nocriticism & that people can come up with all sorts ofideas. Should also be fun laughing – sort of like acreative party with stuff written on the blackboard

Figure 1: Free-Writing Sample


50

2.1.2.6. Brainstorming

A good method for generating a variety of different perspectives and ideasabout a project or problem is brainstorming. Although sometimes used as ainvention strategy by individuals, this technique works especially well insmall groups. It is often worth employing this strategy before using moreformal techniques (such as research) because some effort may well save con-siderable time later doing unnecessary work. At heart, all that brainstorminginvolves is getting a group together and writing down on a blackboard orpiece of paper any ideas which come to mind about a project or problem.

However, you can increase the effectiveness of your brainstorming sessionsby following a few simple rules. First, elect someone as a group leader (oftenthis person also records the information). The leader is responsible for keep-ing the group on task, for assuring that everyone has an opportunity to par-ticipate, and for ensuring that ideas are not dismissed.

Second, a good brainstorming session should be as uncritical as possible be-cause the potential for criticism tends to inhibit the free flow of ideas. Writedown everything that is suggested no matter how silly it might initiallyseem. Ideas may range from the practical to the seemingly insane. Workquickly, writing down anything that is suggested in any order. Do not stopto worry about whether you will actually use a particular point or not anddo not censor your thoughts or anyone else’s. The less structured yourthinking as a group, the more creative it will be. And participants should behaving fun; brainstorming sessions often generate laughter – and sometimesfriends.

Third, people who are brainstorming should ideally come from a wide rangeof disciplines and have widely divergent social and cultural backgrounds.The more diverse the group, the more likely it is to generate unexpected in-sights, ideas, and connections.Once the group has exhausted the possibilities of brainstorming, then theyshould review the points (perhaps at a later meeting), eliminating those thatare unsuitable and further exploring those that are promising.

2.1.2.7. Mind Mapping

Mind maps are ways of generating and visually organizing ideas to showthe relationship between them. Simply take a general idea and write it in thecenter of the page (or on a blackboard); then surround it with more specificideas as they occur to you. Surround these ideas with even more specificideas and so on. If you circle each point and draw lines to the points radiat-ing from it, you end up with something resembling a bug (which is whymind maps are sometimes also called bug diagrams). Figure 2 provides an ex-ample of a mind map.

51


Figure 2: Example Mind Map (Bug Diagram)

Although the above example uses key words, you can also use symbols oricons to represent the various ideas. Nor do you need to restrict yourself tousing one color; you can try using different colors to represent different lev-els of importance or different types of relationships between the ideas.

2.1.2.8. Create Analogies

Creating unexpected or insightful analogies can be a very powerful way togenerate new ideas and thus come up with new or alternative products. Forexample, the analogy of computer screens as desktops and hard disks as fil-ing cabinets enabled the creators of the Macintosh to come up with a newgraphic approach to computing which made computing more accessible tothe average person. Indeed, that particular analogy has proven so popularthat Microsoft Inc. has had very little choice but to devise its competingWindows operating environment.

Part of the reason that analogy is such a powerful tool is that it allows us tosee things from different perspectives. If we view the same event from differ-ent perspectives, we tend to see different things. Take one of Einstein’s ex-amples, for instance. If someone drops a stone from a moving train, that per-son will see the stone descend in a straight line while someone watching thetrain pass by will see the stone falling in a parabolic curve. You can make useof a similar phenomena by exploring a topic from multiple perspectives. One


52

relatively simple method is to consider a subject from static, dynamic, andrelative viewpoints.8

Take three pieces of paper and label each one with a different heading: Static(or Particle), Dynamic (or Wave), and Relative (or Field). On the one labeledStatic, write down anything which pertains to the general description of thesubject as an object, such as its distinguishing features, details, definitions.On the Dynamic sheet, explore the nature of your subject as a process. Thatis, consider how it moves, how its parts relate to one another, what physicaland historical changes it has undergone. On the Relative sheet, explore rela-tionships between your subject and other things. For instance, classify yoursubject as part of a larger group of things; compare it to other similar things;create analogies which relate your subject to different kinds of things. Forthis last view, let your imagination go wild.

If you are unsure what category an idea belongs in, write it down anywhere.The goal of this exercise is to stimulate your imagination and to help you re-call and discover ideas and insights that might otherwise remain unac-knowledged. Do not censor information; write down whatever comes tomind.

2.1.2.9. Generate Contraries

No doubt many of you have seen the following puzzle where you are askedto connect nine dots with four straight lines without taking your pencil offthe paper. Figure 3 shows the initial layout for this puzzle.

Figure 3: Initial Puzzle Layout

Part of the reason this puzzle is so difficult for many to solve is that they be-come trapped by the assumption that they must stay within the boundariesoutlined by the dots. If the person trying to solve the puzzle can recognizethe underlying assumption they are making – stay inside the boundaries –they can easily solve the puzzle by generating a contrary to the assumption –go outside the boundaries. Figure 4 presents the solution to the puzzle.

8 This method of exploring a topic is adapted from Four Worlds of Writing, a textbook written

by Lauer, Montague, Lunsford, and Emig (2nd ed. New York: Harper & Row, 1985). They,in turn, adapted their approach from Young, Becker, and Pike's Rhetoric: Discovery andChange (New York: Harcourt Brace Jovanovich, 1970).Young, Becker, and Pike used a simi-lar method, but instead labeled the viewpoints as particle, wave, and field.

53


Figure 4: Puzzle Solution

Using a contrary is simply a technique for conceptual block busting that in-volves considering the opposite perspective for an assumption that you aremaking when attempting to solve a problem.

For example, a student who recently attended a seminar on résumé prepara-tion was given the following advice – make your résumé scanproof. Making arésumé scanproof involves writing the résumé in such a way as to slow downthe reader. This can be accomplished by using full sentences rather thanpoint form and by rearranging the résumé in such a way as to place impor-tant information such as the dates of employment on the right hand side ofthe résumé rather than on the left (this slows readers down because we readfrom left to right).

Having spoken with someone who knew how senior engineers typicallywent about reading stacks of résumés, however, this student recognized thatthe engineers read them very quickly, spending no more than 30-60 secondson each résumé when initially sorting through them. So this student rea-soned that making a résumé scanproof would more likely frustrate the engi-neer reading the résumé because of the need to slow down. And if frustratedwith the résumé, the engineer might be less likely to place the résumé in thegroup being considered for interviews. The student, therefore, decided that itmight be advantageous to make the scannable (in other words, to make therésumé even easier to read and comprehend in a brief time frame).

The student went about making the résumé scannable by organizing the rés-umé so that important information was easily accessible (dates on the left,previous employers and job titles in bold, and job descriptions in pointform). Yet the student wasn’t completely satisfied that this made the résuméas scannable as possible, so he reasoned that the reason senior engineerscould read the résumés so quickly was because they were looking for keywords.

After recognizing this, the student further reasoned that he could help outreaders of his résumé even more by bolding those key terms that were rele-vant to the position he was applying for. So if one of the key skills neededfor the position happened to be programming with C++, he ensured that hebolded these words (along with the words describing a few other relevantskills). Although this might not guarantee that the student’s résumé endedup in the group to be interviewed, by applying the contrary to making


54

résumés scanproof (and then by extending the contrary in a reasoned man-ner), he certainly increased his chances that the reader would see the termsand note that the applicant had the required skills.

2.1.2.10. Synthesize Ideas

To synthesize ideas simply means to bring seemingly unrelated ideas to-gether in order to see what results. Synthesizing requires being observant ofthe world around us and keeping an open mind. Consider, for example, theexperience of the inventor of the Post-It Note ( 3M Co.), Art Fry:

He thought of the idea by accident sitting in church. As a choirmember, he was stumped about how to keep the pages marked in hischoir book. During a “dull” sermon he mulled over the problem. Back atthe office a fellow scientist had found an adhesive that didn’t stick well,while trying to invent a super glue.

It hit Fry. Could he use the adhesive on a piece of paper as a remov-able book mark?

He perfected the product and started testing it as a book mark withcolleagues. Then, one day he wrote a memo on it to his boss and at-tached it to a report. The Post-It was born.

“We knew we were on to something but it was a difficult sell,” re-called Fry. Others in the company thought it was a dumb idea. It wastoo simple. Office supply dealers said it would never sell.

“The people that used them just swore by them,” said Fry. The restis highly profitable history.9

Figure 5: The 1st Post-It Note®

Although the discovery of the adhesive itself is a good example of serendip-ity (an accidental or lucky discovery), inventing the Post-It Note requiredthat Art Fry synthesize several disparate things into a useful product: the ad-

9 Carol Howes. June 9, 1995. “Post-It inventor still sticking with his science” in The Vancouver

Sun, Pacific Press Ltd. Vancouver, BC, pp. D1.

55


hesive, the paper, and the need for bookmarks. By recognizing his own needto mark his choir book and by recognizing the potential of the failed super-glue, Fry was able to come up with a remarkably successful invention. Allthat remained, then, was to sell the idea to his supervisor, others in his com-pany, and office supply dealers (perhaps the most difficult part of the job).

2.1.2.11. Ask Questions

Asking yourself the right kinds of questions is one of the keys to successfulwriting. A question heuristic is a list of questions that directs a writer’s at-tention to the concerns which should be addressed and to the informationwhich should be included. The journalistic formula – Who? What? When?Where? Why? How? – is probably the simplest and most widely used ques-tion heuristic. Many successful writers create lists of questions appropriateto a particular situation and use these questions as a guide to help themgenerate and organize ideas. We encourage you to get into the habit ofasking questions as a means of generating ideas. For example, a specificaudience/purpose heuristic for an informative report could include thefollowing questions:

Who is my audience?

• Who will read this report? (i.e., Technical experts? Administrators?Business people?)

• Why will they read it? (i.e., What motivated them to request the re-port? What actions will or can they take on the basis of this report?)

• What information have they requested? (i.e., Are their instructionsclear or do they need clarification?)

• How well informed are they about the subject? (i.e., How much back-ground information is required? Are they familiar with technicalterminology?)

• What information do they need? (i.e., Do I have all the informationneeded to write the report? If not, what do I need to find out and howwill I do so?)

What is my purpose?

• What do I hope to accomplish by writing this report? (i.e., Can I writea clear, concise statement of purpose?)

• How do my objectives relate to my reader’s expectations? (i.e., Dothey share my objectives? If not, what are the points ofdisagreement?)

• How can I meet both my objectives and my reader’s expectations?(i.e., What do I know that they do not and how can I make themaware of it?)

• What attitudes or values do they have that must be taken intoaccount?

Remember that any list of questions serves only to direct your thinking.Questions should generate other questions which relate specifically to a par-


56

ticular audience and purpose. The trick is to ask the right questions; goodquestions generate appropriate answers.

Finally, as a word of caution, we offer you the following “Fifty Phrases thatKill Creativity.”10 Watch for and avoid them as you are brainstorming and asyou move on in your career.

1. We tried that before.2. Our place is different.3. It costs too much.4. That’s not my job.5. They’re too busy to do that.6. We don’t have the time.7. Not enough help.8. It’s too radical a change.9. The staff will never buy it.10. It’s against company policy.11. The union will scream.12. Runs up our overhead.13. We don’t have the authority.14. Let’s get back to reality.15. That’s not our problem.16. I don’t like the idea.17. You’re right, but...18. It’s impossible.19. We’re not ready for that.20. It isn’t in the budget.21. Don’t rock the boat.22. Good thought, but impractical.23. Let’s give it more thought.24. It can’t be done.25. Not that again.

26. Where’d you dig that one up?27. We did all right without it.28. It’s never been tried before.29. Let’s put that on the back burner.30. Let’s form a committee.31. I don’t see the connection.32. It won’t work in our plant/office.33. The executive committee won’t go for it.34. Let’s all sleep on it.35. We’d be the industry laughingstock.36. It’s too much trouble to change.37. It won’t pay for itself.38. You’re two years ahead of your time.39. I know a person who tried it.40. We’ve always done it this way.41. Top management won’t buy it.42. We’d lose money in the long run.43. Can’t teach an old dog new tricks.44. That’s what we can expect from staff.45. Has anyone else ever tried it?46. Let’s look into it further (later).47. Quit dreaming.48. That won’t work in our school.49. That’s too much ivory tower.50. It’s too much work.

As should be apparent from the nature of the list, the above phrases tend tooriginate most frequently in large companies and schools with rigid rulesand hierarchical structures. Creativity is generally hampered when peopleare most concerned with job advancement or job security. Creativity is usu-ally enhanced in more democratic and less structured environments. Youmight keep that point in mind as you go about organizing engineeringteams.

2.1.3. Project Phases and Project Documentation

Although in ENSC 305 you will not be expected to complete all the docu-mentation or follow all the phases of an engineering project, the followingtable summarizes the design phases of major engineering/software projectsand indicates what documentation would typically accompany each phase.The particular approach outlined below is that of top-down design (sometimesalso called the systems approach).

10 Source: Dave Dufour, CompuServe Information Service, 72757,3047 (1993).

57



58

2.1.4. Proposals

2.1.4.1. General Considerations

A company or government department issues a Request for Proposal (RFP)when they require that a product or service be custom designed for them (anInformation for Bid— IFB— is used for a standard product). Sometimes anRFP is a very lengthy detailed set of technical specifications andrequirements.

Indeed, when the American defense department issues an RFP, its lengthcould just as easily be measured by how many inches or feet thick it is as bythe number of pages it contains.11 And, in some cases, the Response to a Re-quest for Proposal (RRFP) is equally large. In one case, for example, “The re-sponse to a Request for Proposal, RFP, for a modest size development pro-gram was so heavy (the required number of copies of this very thick docu-ment weighed 4,000 pounds) the corporate jet couldn’t handle it and a 737had to be leased for $25,000 to carry it a few hundred miles.”12

In other cases, an RFP may simply be a general statement of goals which re-quires the engineering firm to create their own designs to meet the client’sgoals. In the ENSC project courses, you are given considerable latitude as tothe nature of the project you undertake. You might, for example, prepare aproposal outlining a device that you will build for an instructor, for a privatefirm or government agency, or that you are interested in building for yourown use.

As you will note, the term RRFP and the word proposal have been used inter-changeably throughout this module. This has been done because in somecases you may actually be responding to an RFP (formal or informal) whilein other cases you may be proposing to build a device for your ownpurposes.

Keep in mind that Responding to a Request for Proposal is a competitiveprocess. Often a client gives the same RFP to several different groups in thehope that one of them will offer an advantage which the others may not. TheCanadian government, for example, often submits important RFP’s todozens of engineering firms.

The sort of advantage a client might be looking for could be a lower cost, anearlier completion date, a higher quality product, or a more marketableproduct. Because an RRFP must compete with others, it must not only be in- 11 As an example of just how detailed defense department documents can become, you

might consider the case of the U.S. Military Specification for Cookies, Oatmeal and Brownies,Chocolate Covered (MIL-C-44072C, April 1990). The specification for these two rather simplerecipes is 22 pages in length and cites over 20 other government documents. To actuallymake the cookies and brownies to specification would require reading several hundredpages of documents.

12 Source: Charles Fowler, “The Defense Acquisition System Too Late for the Scalpel; BringOut the Meataxe!” in IEEE Aerospace and Electronic Systems Magazine. (August, 1994, p. 3).

59


formative, but it must also be persuasive. In general, you must convinceyour client of three things: that you understand the client’s needs, that youpossess the expertise (and, in some cases, the facilities) to design and deliverthe device, and that the benefits outweigh the costs. In other words, youmust persuade your client that your proposal is realistic.

2.1.4.2. Reading the RFP

In order to persuade the client (or the instructor) that you understand theirneeds you must read the RFP very carefully. If possible, several individualsshould read through the RFP. Ask yourself the following as you read theRFP:

1. Can you actually do the project? In other words do you possess thenecessary expertise? What additional information do you need to ac-quire? And how soon would you need to obtain that information inorder to complete the project?

2. When is the RRFP due? Can you meet that deadline?3. What does the client say they need? What constraints in terms of

time, size, cost, and safety are mentioned? What does the client reallyneed? What is possible? (Note, for example, that you should not starta project for which the budget is insufficient.)

4. What alternatives exist ? Does a similar system already exist?5. How long will this take?6. How much will it cost?7. What are the possible technical solutions?8. What issues of safety and ethics are involved?9. What information that you need has the client left out?

If, after reading the RFP thoroughly and considering the above questions,you find you don’t understand something (or important information isomitted), contact the client for clarification and record the information. Alsoensure that you exactly adhere to the directions for submitting the proposal.In industry, proposals which do not provide all the required information areoften rejected and late proposals are typically returned unread.

2.1.4.3. Content Considerations

In the body of the RRFP or proposal, you must very carefully and compre-hensively define the nature of the problem to be addressed or solved by yourdevice. What precisely is the device intended to do? Your proposal should bemainly written from a functional perspective rather than a design perspective.

In other words, if you are proposing to build a temperature controller, youneed to define what the device does, why the device is needed, where itmight be used, who might use it, etc. You should not provide much detailabout how you specifically intend to solve the problem or build the device.


60

If you expend a lot of energy designing a solution to a problem you do notyet fully understand, you are simply wasting your time! The problem mustbe defined fully before you start proposing detailed solutions!

Nevertheless, you should include a few potential alternatives for solving theproblem and you should also include your recommendations as to whichpossible solution seems most appropriate. Keep in mind, however, that thesealternatives and recommendations will remain quite tentative and generaluntil later in the design process. If your recommended approach to theproblem is an innovative one, you should clearly explain the advantages ofyour approach over the alternatives. This explanation is particularly impor-tant if your approach is more expensive than some of the alternatives. Whatadditional benefits can the client expect for the increased cost?

You should provide as much specific detail as possible about your plan forthe project. Where do you propose to obtain the materials? What will the de-vice do? How will you measure its performance? What are the limitations ofthe device? Is there a similar device already on the market? What are itslimitations in terms of functionality and cost? What standards for qualitycontrol do you propose? What standards must be met (e.g., ISO, MIL, IEEE,etc.)? What issues of safety are involved? How will you deal with them?How feasible is the project given your constraints of time, funds, and exper-tise? And what precisely are those constraints? Who is the user? What aretheir limitations in terms of knowledge, manual dexterity, etc? What trainingwill they require?

If the project requires that you deal with a particular system, you should alsodevote some space to discussing the system. For example, if your project re-quires knowledge of the Musical Instrument Digital Interface (MIDI), youdemonstrate that you are familiar with MIDI by discussing it in generalterms.

You should also include a section which provides a condensed description ofthe skills of your team. Who has expertise in what areas? If someone has pre-vious design experience, this should be noted. In the case of the projectcourses, you may choose to assign roles to the various team members basedupon their expertise (i.e., electronics engineer, programmer, documentationspecialist, chief executive officer). You may also provide the résumés of yourteam members in an appendix.

You are also expected to provide a budget estimate and a preliminary sched-ule in your RRFP. The schedule should include both a Gantt Chart, whichoutlines when the various tasks will be carried out, and a Milestone Chartwhich details the various milestones and deliverables for the project. Thefollowing figures provide examples of Gantt and Milestone charts for writinga report.

61


Weeks

0 1 2 3 4 5 6 7 8 9 10

Deliver Report

Format Report

Final Editing

Revise 1st Draft

Create Figures

Write 1st Draft

Research Topic

Figure 6: Example of a Gantt Chart

1 2 3 4 5 6 7 8 9 10

Complete CompleteFigures

CompleteRevised

Draft

CompleteEditing

CompleteFormatting

Report

by Client

Weeks

ReceivedResearch& 1st Draft

Figure 7: Example of a Milestone Chart

2.1.5. Functional Specifications


Once you have completed the proposal phase of the project and your RRFPhas been given preliminary approval by the client or instructor, you start theanalysis phase of the project. The Functional Specification defines WHAT thesystem or device must do for the client and forms the basis for the agreementor contract between you and the client. The more comprehensive and clearthe Functional Specification, the more likely the project is to arrive at a suc-cessful conclusion.

Consequently, you must avoid the temptation to immediately start workingon the design phase of the project (the HOW). As with the proposal, untilyou have a sufficiently detailed understanding of what the problem is andwhat the system must do to solve the problem, you cannot determine how tosolve the problem. The quality of your design depends critically upon howcarefully you go about analyzing the problem and the required functions.


62

2.1.5.2. Analysis of the Problem

To produce a useful Functional Specification, you need to analyze the natureof the problem in some detail. The following are some of the steps which youshould follow in order to achieve that goal. Note that the first two pointsonly apply to designing an improvement to an already existing technique,product, or technology. For novel technologies or products, points 3 and 4are especially critical to the success of the project. The remainder of thepoints apply to both circumstances.

1. Collect all available information about the project, including the RFP,the RRFP, and any notes produced by the client or user.

2. Identify and meet with the real user of the proposed system. Al-though the user may be the client, at other times the user may besomeone else within the organization. Pick the user’s brain. What arethe minimal requirements of the user? What would they like thesystem/device to do under ideal circumstances (i.e., what is theirwish list)? Also meet with the decision makers and determine theirrequirements (i.e., costs and benefits). Remember that both the userand the decision maker must be satisfied with the outcome.

3. Do a thorough analysis of the physical and theoretical phenomena in-volved in the performance characteristics of the idea/product. Some-times this analysis will show you that what you are proposing is notpossible in light of some fundamental law of physics or chemistry. Inother words, use some simple logic to determine if your conceptmakes sense.

4. Do a practicality analysis in order to determine if your idea can beturned into a saleable product. A device that is technically feasiblebut unsaleable (e.g., too expensive, too difficult to use, etc.) maysimply be a waste of time.

5. Examine the system that is currently being used to complete thetask(s). This will help provide insight into the “real” (rather than thestated) problem and needed functions. In addition, this sort of inves-tigation will reveal some of the design constraints that you face andmay also provide you with some ideas for improvements that youcan suggest to the client.

6. Analyze the collected information and define the issues which needto be resolved. During this process, create a list of questions whichneed to be answered.

7. Collect answers to those questions and then analyze those answers.Interviews, meetings, tours, and observation can help answer thequestions.

8. Define the system or device conceptually. One way to do this is byworking backwards from the output through the functions and proc-esses in order to determine what inputs are required.

9. Review the definition of the problem and the functions with the usersof the system.

10. Negotiate any changes that are required and obtain approval. One problem that is occasionally encountered with this approach is analysisparalysis which occurs when the user continues to suggest new features for

63


the proposed system so that it becomes difficult to conclude the analysis.One solution to this problem is to suggest the user consider multipleprojects.


In the body of the Functional Specification, you are expected to include aclear and detailed description of the required functions of the device or sys-tem. Ensure that you describe the elements of the system in terms of theirfunction and not in terms of their design. For example, “In order to protectthe internal components, the package for the unit will be rigid” is afunctional description while “In order to protect the internal components,the package for the unit will be sheet steel” is a design description.

As much as possible avoid the use of jargon and technical terminology. Ingeneral, the user should be able to understand the Functional Specifications.If some technical terms must be used, you should either clearly define themin the text or include a glossary.

Some of the things which might be found in the Functional Specifications in-clude normal operating conditions (i.e., temperature, altitude, humidity),power, heat dissipation, size, weight, packaging, safety features, reliability,response times, compatibility with other systems, known system limitations,documentation, training (if required), the user interface, etc.

Those specifications which apply for the entire system should be describedimmediately following the system overview. Usually a single paragraph isdevoted to describing each function. Those specifications which only applyto a particular functional component should be detailed in the sub-sectiondevoted to describing that component. In complex systems, you are advisedto make greater use of tables rather than text as this approach is far moreconcise. For an example of these tables, look at the specification sheets forstereos, amplifiers, etc.

2.1.6. Design Specifications


In the words of H. L. Mencken, “for every problem, there is a solution that issimple, plausible, and wrong.” His wise words apply most especially to en-gineering design problems. Perhaps one of the most frequent mistakesmade by individuals learning the design process is that of settling uponthe first design which comes to mind.

Unfortunately, this mistake can have serious consequences. Sometimes thehasty acceptance of an initial (often conceptually flawed) design results insubstantial work being performed on the hardware and software before thepitfalls of the design are discovered. At the very least, this sort of hasty deci-sion might lead to a minor, but frustrating, waste of the design team’s time;


64

in more extreme circumstances, it can result in large financial losses (not tomention someone losing their job). In other words, you should consider sev-eral possible designs. Perhaps one of the most fruitful ways of generatingalternative solutions to the design problems is through group brainstorming.

In general terms, the Design Specifications describe HOW the various func-tions outlined in the Functional Specifications will be implemented. Thevarious sub-systems which are outlined in the Functional Specificationsserve as the basis for organizing the Design Specifications. In addition, thisdocument specifies the design conventions and standards which will be usedthroughout the development process. The Design Specification acts as a“road map” to keep the implementation on track and to ensure that all re-quired functions are implemented.

Usually, the Design Specifications for a project are generated for the internaluse of the engineering firm and are not provided to the client. In part, this iscommon sense; often the Design Specifications are so technical in nature thatthe average client would not find them understandable. In the case of theproject courses, however, you are expected to provide a copy of the DesignSpecifications to the instructor.


In the Design Specifications, you should provide an overview which de-scribes the overall system (include a system block diagram as in Figure 8,below) as well as the objectives of the system (i.e., how the system benefitsthe client). In the body of the document, however, you should provide a de-tailed description of the design for each sub-system. These descriptionsshould be accompanied by figures, diagrams, and sketches which are clearlylabelled in terms of their dimensions, power, etc.

You are also expected to explain why you have chosen certain materials, so-lutions, algorithms, or approaches for the design. When appropriate, theseexplanations should be backed up with the physics, mathematics, and stan-dards necessary to account for what is going on. Finally, ensure that you ad-dress the issue of ergonomics; for instance, be sure to consider the user inter-face, providing details of its size, composition, behavior, etc.

65


Figure 8: Example of a System Block Diagram13

2.1.7. User’s and Technical Manuals


Entire books have been written about how to produce effective user’s andtechnical manuals; unfortunately, our description can do little more thantouch upon a few important points. If you desire further information, wesuggest you read through one of the many books available. In particular, werecommend How to Write a Usable User Manual by Edmond H. Weiss(Philadelphia, PA: ISI Press, 1985) because it provides a useful perspectiveabout writing manuals— manuals are viewed as devices which must be care-fully engineered to meet the needs and expertise of the user. We endorse thisviewpoint and hope you will as well. In general, four basic principles under-lie the production of User’s and Technical Manuals: safety, accuracy, dura-bility, and ease of use.

To emphasize the importance of engineering your User’s Manuals, we relatethe following (mostly) true story. The names are changed to protect theguilty parties.

Once upon a time, a person (who shall remain nameless) owned a verylarge, very green, and unfortunately, very broken truck. The person,who also happened to be very broke at the time, decided to save somemoney by repairing the truck himself. Not being very mechanically in-clined, he realized that he would need to purchase a manual about truckrepair. So off he went to the bookstore. And he asked the clerk, “Do youhave any books about fixing big green broken trucks for the not-very-

13Figure 3 was adapted from Functional Specifications for the Microelectronic Process Controller

by C. Lee, G. Marks, D. Pon, D. Spencer, G. Wei, and B. Woodley (Burnaby, BC: School ofEngineering Science, Simon Fraser University, 1990, p. 3).


66

mechanically-inclined?” And the clerk responded, “Yes, I believe wehave just the thing for you.” The clerk went to the back of the store andbrought back a very large book entitled The World’s Best Manual forRepairing Big Green Trucks that Belong to the Not-Very-Mechanically-Inclined. So our not-very-mechanically-inclined hero purchased the bookdespite its cost of forty dollars. After all, it promised to be the world’sbest. And it was written by that expert on mechanics, Monk E. Wrensch.

When he arrived home, he immediately opened the manual to thechapter about broken clutches (that, it seems, was evidently the prob-lem). And the chapter started out with the words “After you have re-moved the transmission . . . .” “No problem,” thought our hero, “All Ihave to do is remove a few of them big screws.” So he set to work withall the new tools he had purchased for a mere fifty dollars. After easilyremoving all the big screws (which turned out to be bolts) and discon-necting the drive shaft, he was ready for the next step, removing thetransmission. But, for some inexplicable reason the transmission didn’twant to be removed. It seemed to be stuck. “Well maybe if I use aprybar to push it out, then I can get on with fixin’ the clutch” So hepurchased a prybar (for another ten bucks), crawled back under thetruck and started prying at the transmission. He sweated. He swore. Butmostly he pried. For a whole hour he pried at that transmission, butonly moved it out by four inches. Just enough so he could clearly see thetransmission drive shaft.

Now while he was a-sweating and a-swearing, a neighbor dropped byto borrow our hero’s lawn mower. It seems this neighbor was one ofthose strange people who, by some perversity of the gods, are exceed-ingly mechanically inclined (although our hero could never quite figureout why the neighbor couldn’t fix his own lawn mower). So this neigh-bor looks at the pair of legs sticking out from under the big greenbroken truck and asks “Whatcha doin?” Our hero answers in asomewhat strangled voice, “I’m pryin’! This here transmission’s stuckand I gotta get it out to fix the clutch!” And the neighbor says “Stuck,huh?” “Yah, its stuck, #&%@ stuck,” he replied. There was a silence fora few minutes and then the neighbor says, “Well, I guess youremembered to put a jack under the engine, eh?” “Huh? Whadaya meanjack under the engine?” responds our hero. “Well,” says the neighbor,“If you manage to get that transmission out without somethin’ to holdup the engine, the engine’ll fall right out. Lands on you, it’ll squish youlike a bug.”

Well, our hero got out from under that big green and still very broketruck mighty fast. And mighty angry. And he went and read throughthat manual entitled The World’s Best Worst Manual for Repairing BigGreen Trucks that Belong to the Not-Very-Mechanically-Inclined from coverto cover. Nowhere in the entire eight hundred and some odd pages didthat manual mention anything about putting a jack under the engine.

Now, this here story has a happy ending. Despite the bug in themanual, our hero was lucky enough to avoid getting squished like one.

67


He did try to return that manual to the store, but they wouldn’t take itback. Seems there was a problem with the grease on the pages. Still, hedid eventually manage to fix that broken clutch. Of course, first he hadto spend a hundred dollars on jacks to hold up the engine. That wasquite all right though, because he needed all those tools about a monthlater when he had to replace the transmission. Seems there was somesort of problem with a bent drive shaft on the transmission. But that’sanother story.

As we hope this story demonstrates, you must make every effort to idiot-proof your User’s Manual, particularly when written for an audience withless technical expertise than yourself and safety issues are involved. Minorflaws in a User’s Manual may simply frustrate the user; more critical flawscan lead to property damage or personal injury, thereby resulting inlitigation. Pay careful attention to the potential risks and dangers which maybe related to your system or device. A what-if type of analysis is one of thebest approaches if you use your imagination and common sense. Andalways clearly warn the user about these dangers (i.e., warning messages arebest printed in a large font and bold-faced).

!! ATTENTION !!

Print Warning Messagesin a Large Bold Font

Figure 9: Example Warning Message


For the project courses, you will only be required to write a User’s or Techni-cal Manual if you are working on a project for a client external to the univer-sity.14 If you are writing a manual, you are advised to combine the User’sand Technical Manual into a single document of about 20 to 30 pages. Be-cause User’s Manuals and Technical Manuals are written for audiences withvery different levels of expertise, this can be a difficult task.

Perhaps the simplest solution is to place most of the technical informationinto appendices. Another solution is to divide the Manual into separate sec-

14For ENSC 370, you will instead be asked to write a “process” report which describes the

evolution of your project and analyzes your successes and failures— 8 to 10 pages inlength.


68

tions or chapters, one of which emphasizes the technical aspects of thedevice (i.e., how to modify or repair the unit) while the other sectionemphasizes operating the. device. In general terms, the manual shouldprovide a complete description of how the device operates from on to off,including initial set up, testing subsystems, trouble shooting, safety, etc.Usually, you also include a summary of basic functions and a quickreference card.

2.1.7.3. Format, Organization, and Stylistic Considerations

Prior to writing the User’s Manual, you must very carefully review the sec-tion entitled “Cognition and Information” in Chapter Three. You are ex-pected to format and organize the User’s Manual in a fashion that assists thereader. Evaluate your organization and format from the reader’s perspective.But remember they know less than you do (note, however, that this is notthe case with the Technical Manual). If at all possible, ask someone with theuser’s level of expertise to read through a draft of the manual.

The following lists detail some of the issues relating to format, organization,and style which you should consider while working on the manual.

2.1.7.3.1. Formatting Considerations

1. Use more white space than usual (i.e., use wide margins, start newsections on a new page).

2. Use an ample number of figures and tables.3. Draw attention to important information by boldfacing, using a large

font, or placing it in a box.4. Repeat important information in each section. Make use of organizers

(i.e., “In the last section you learned . . . . In this section you willlearn . . . .”).

5. Include an introduction and summary for each chapter or majorsection.

6. Be consistent with headings, organization, etc.7. Include a Trouble Shooting section and a Frequently Asked

Questions (FAQ) section8. Provide a quick reference card.

2.1.7.3.2. Organizational Considerations

1. Ensure your headings accurately represent the information containedwithin the section.

2. Provide a table of contents with two or three levels of headings (andan index if the document is sufficiently lengthy).

3. Use an organization appropriate to your audience:

69


a) A task oriented organization (i.e., installation, start-up, write,edit, save, etc.) is often most appropriate for the average user.

b) An option/component oriented orientation (i.e., Menu 1, Sub-Menu 1.1, 1.2, Menu 2, Sub-Menu 2.1, etc.) is often most appropri-ate for those with a high level of technical expertise.

4. Move from non-technical to technical, from general to specific, fromsimple to complex.

5. If possible, avoid Go To instructions (i.e., instructions that refer theuser to another part of the manual.

2.1.7.3.3. Stylistic Considerations

1. Write in the 2nd person rather than the 3rd person (i.e., “When youdo X, then Y happens” rather than “When the user does X, then Yhappens”).

2. Use verbs with a precise meaning rather than more general verbs(i.e., use calculate, print, or record rather than make).

3. Use the active rather than the passive voice (i.e., “We built this deviceto monitor the humidity in the room” rather than “This device wasbuilt to monitor the humidity in the room”).

4. Avoid using unnecessary jargon. Include a glossary for those techni-cal terms which you must include.

5. Use shorter sentences and paragraphs than usual.6. Use examples in your explanations.7. Use metaphors and analogies that are appropriate for your user.8. Use humor if possible. A user who is having fun is generally also

learning. (However, exercise some caution here; users with a highlevel of technical expertise may find an overly “folksy” approachintrusive.)

Figure 10: Example of a Less-Than-Helpful User’s Manual15

15This figure reproduces the complete user’s manual that accompanied a device with a

rather unusual purpose. Can you guess what the device is and what the user’s manual isattempting to tell the reader? See Steve if you have any theories or are completely baffled.


70

2.1.8. Progress Reports

At regular intervals throughout the ENSC project courses, you will be ex-pected to provide written progress reports to your clients (or the instructors).These progress reports are to be a maximum of two pages in length and maybe written in either memo or e-mail format. Their purpose is to clearly andconcisely update the client about the progress of the project. These reportsshould detail where you are in respect to the original schedule (work com-pleted, work remaining, changes to the schedule), and the original budget(funds expended, funds remaining, changes to the budget). Be specific.

In addition, they should detail any changes to the overall terms or scope ofthe project. If you are behind schedule or over budget, you are expected toexplain why and arrange an appointment with your client to discuss howyou propose to resolve the problems. Please ensure that you provide a date,signature, and contact number on these reports.

2.1.9. A Final Point about Project Documentation

Although producing all the above documentation may seem like a lot ofwork, you should keep a couple of points in mind. First, remember that allthese documents are collaboratively written. Thus the task of writing is actu-ally divided among three or four individuals. Second, the work you under-take for the project documentation course has a clear payoff in the profes-sional world. In traditional engineering courses, you are not usually pro-vided with the opportunity to practice writing as part of a team. But this sortof experience is precisely what many employers are looking for. Your mas-tery of group dynamics and collaborative writing may well provide you witha competitive advantage as you seek employment.

¦

71


3. Chapter Three: Formatting for the Reader


73


74

3.1. The Importance of Form

[ Format and Community[ Writing to Inform[ General Principles of Format

ONSIDER, FOR A MOMENT, TWO recently graduated engineers apply-ing for employment with an established corporation. The first isquite well qualified for the position. She has relevant work experi-

ence and a good academic record. However, she wears to the interview adirty T-shirt, cut-off blue jeans, and torn running shoes. Further, she has notbathed for several days and has long unkempt hair.

On the other hand, the second engineer is only moderately qualified for theposition. His experience is limited and his academic record is mediocre.However, he dresses appropriately for the interview and is generally wellgroomed.

If these are the only two applicants, which of the two is the most likely toobtain employment with the company? In most circumstances, the well-groomed applicant will be successful. Why? Simply because appearancesmatter. By dressing appropriately, the second engineer demonstrates a pro-fessional attitude and, of equal importance, respect for the interviewers.

Obviously the above example is extreme. No one who is seriously seekingemployment would dress in such an inappropriate fashion. Nonetheless,you would probably be surprised at how frequently people submit sloppyrésumés and covering letters to prospective employers. These individualsare rarely successful in obtaining employment.

Sadly, the same may be said of documents sometimes submitted by both en-gineers and engineering students; the content is good, but little attention hasbeen paid to the form of the document. We have seen reports lacking pagenumbers, tables of contents, lists of figures, or lists of references. We haveseen other reports which were nearly illegible because of a poor choice offont or inferior quality photo-reproduction. In other reports, the authorsfailed to label figures, placed the figures in inappropriate locations, or sub-mitted sloppy pencil-drawn figures. The attitude seemed to be that “I ambeing evaluated on the content, so why should I bother worrying about howthe report looks?”

C


75

3.1.1. The Relationship between Form and Content

Unfortunately, this “who cares?” attitude toward format is based upon theassumption that form and content are easily separable. They are not. Formany years, form was viewed simply as an empty container into whichideas could be placed. And when viewed as an empty container, theassumption was that we could pour any sort of content into it and the formwould function adequately But, in the real world, is this actually the case?There is, after all, a reason we do not drink our morning coffee or tea out of atwo gallon bucket. The bucket is too large and cumbersome to easily drinkfrom. Because of the larger surface area, hot liquids tend to cool morequickly than desirable in large containers. And so on.

In other words, this container metaphor is a poor one for the relation be-tween form and content and has sometimes led to a disregard for the impor-tance of form. Without form of some type, be it well or poorly considered, nocontent can be communicated. Even what is sometimes described as “emptyform” (a document that looks appropriate in form but seems lacking in sub-stance) communicates information, if only to suggest that the writer has verylittle to say or doesn’t care much about the topic. Even the word “in-form-ation” implies that ideas must be structured in some fashion or other.

Both form and content communicate information, but they do so in differentways. To better understand the relation between form and content, considera speaker: his or her words communicate information in an explicit, linearfashion; his or her body language communicates information in a more sub-tle, multi-layered fashion. Ideally, if the speaker is to be most effective, thetwo types of communication should complement and reinforce each other.Different kinds of content require different forms. Consider, for example,why love letters are not written in a business letter format.

A better metaphor for the relation between form and content is that of agrowing plant.16 Throughout history, form has grown organically in a waythat supports the content. The two are inseparable. Over many years,various forms have grown, evolved, in ways that are functional in terms ofcommunicating information within the discipline of engineering. And just asplants grow in different shapes and sizes to support different kinds of fruitsand seeds, so too the forms of documents come in different shapes and sizesto accommodate different kinds of information.

And these rhetorical forms are not easily interchangeable. Consider thegenre of the essay frequently used in the Humanities. Although occasionallyused in the discipline of Engineering, it is not a very commonly encounteredform. Or consider the genre of the lab report that is so frequently relied uponin Engineering and the Sciences. The lab report genre is rarely used in theHumanities. If you were to submit a lab report written using the essay form,you probably wouldn’t be too surprised to receive a low grade than if youused the lab report form.

16 We would like to thank Rick Coe (Simon Fraser University, Burnaby, BC) for devising this

metaphor and for demonstrating how it applies within various disciplines.


76

All else being equal, the difference in the grades received by students sub-mitting well-formatted documents using the appropriate rhetorical formsand those submitting poorly formatted documents using inappropriate rhe-torical forms is about 10 to 15%. Assuming both documents demonstrate amastery of the required engineering concepts, this 10-15% is the differencebetween an “A” and a “B” or “B+”.

If we extend this reality beyond the realm of the classroom, into the world ofwork, we can speculate that the difference between submitting documents ofan appropriate or inappropriate form to your supervisors may well be thedifference between being promoted and receiving a raise or being passedover. If for no other reason, it is worth mastering form to elevate your gradesand perhaps eventually increase your earnings.

3.1.2. Rhetorical Form and Community

Why does form have this impact upon grades and promotions? In part theanswer to this question lies with the individual who reads the document.From their past experiences within a discipline, most readers have acquireda set of expectations about how the document will organize and present in-formation. For both writers and readers, the form of a document helpsstructure the search for information and helps determine how easily that in-formation will be comprehended. Moreover, appropriate form also commu-nicates your abilities and attitudes to the reader:

• Are you able to deal with all the subtle details and implications of agiven topic? (Appropriate form communicates attention to details.)

• Are you able to think in the logically organized ways expected of en-gineers? (Appropriate form communicates attention to organization.)

• Do you have a sufficiently positive attitude toward the topic that youwant to present it in the best possible fashion? (Appropriate formcommunicates interest.)

• Do you have a sufficiently positive attitude toward your reader thatyou are willing to present the information in the most easily compre-hended fashion? (Appropriate form communicates respect.)

• Do you have a sufficiently professional attitude that you are willing todevote the time to producing first-rate documents. (Appropriate formcommunicates dedication.)

Taken together, these five points about form can communicate to the readerwhether or not you are a member of the professional community of engi-neers, whether or not you understand the preferred ways of organizing andpresenting information – the preferred ways of thinking. As a student seekingadmission to this professional community, your attention (or lack of atten-tion) to form may well communicate to members of this community the de-gree to which you are deserving of admittance.


77

In fact, it can be argued that the thesis or project report you may need tosubmit to complete your degree requirements tests your mastery of both theforms and concepts of engineering. And, as you will quickly discover,should you submit a thesis or project report written in a non-standard ornon-professional form, you will usually be required to undertake extensiverevision.

Form matters – not only by influencing the success of your subsequentcareer as an engineer, but also by influencing your success in gainingadmission to the community of engineers. You would thus be well advisedto master the various rhetorical forms required in engineering as soon aspossible.

By using the appropriate rhetorical forms you communicate to the audiencethat you are a professional who shares certain beliefs, values, ideas, andmethods with them. You demonstrate your authority. Moreover, you com-municate to the audience that you are attentive, organized, interested, anddedicated. On a more subtle level, proper format displays respect for thereader. You help your audience identify with you as an individual who canbe trusted. In other words, the form you choose for a document serves a per-suasive as well as an informative purpose.

The details of form make an important first impression upon the reader. Infact, under some circumstances, the appearance of a document may make amore important impression upon the reader than the information containedwithin the document.

For example, the busy senior engineer or administrator may sometimes lackthe time to read an entire report, particularly if the report is lengthy or ex-tremely complex. What they will read is the table of contents, the abstract (orexecutive summary), the introduction, and the conclusion. Then they mayscan the document, examining some of the figures and tables.

If the document appears professional and the readers see no problems(including, by the way, spelling or grammatical errors) in the sections theydo read, you can reasonably expect they will accept the report. On the otherhand, if the document looks unprofessional, probably it will be returned formajor revisions – even if the content is acceptable. For some audiences andpurposes, then, you may find it helpful to expend proportionally more timeand effort on certain elements of your documents while drafting andrevising (most notably, the abstract, the introduction, the conclusions, as wellas the figures and the tables).

3.1.3. Rhetorical Form as Dynamic

As we mentioned earlier, the metaphor of form and content as a growingplant is a useful one. Beyond simply indicating the organic relationship be-tween form and content, the metaphor also draws our attention to the factthat form is not static. Rhetorical forms evolve over time in response to theneed to communicate different kinds of information for different audiences


78

and purposes. In fact, over the next few decades we may well witness a ma-jor change in rhetorical form as our traditional paper documents shift frombeing linear and static in nature to the newer electronic documents basedupon dynamically changing information and hypertext links (a connectionbetween two separate locations in a document or between documents).

We need only peruse the World Wide Web (WWW) or read some on-goingconversations in the Usenet Newsgroups to observe the rapidly changing na-ture of rhetorical form. The use of links on the WWW is changing the waywe read. Instead of reading a document in a linear fashion, from beginningto end, we now can follow the link from specific information in oneelectronic document to related information elsewhere in the same documentor in another document. Because these links are added and deleted, often ona daily basis, electronic documents also tend to be more dynamic than paperdocuments. When following the links of electronic documents, what we endup reading tomorrow will almost certainly be different from what we readyesterday.

On the Usenet, documents such as FAQ’s (Frequently Asked Questions)change frequently in response to questions and feedback from readers. Un-like paper documents, the ability to communicate directly with the authorsof such documents (and others who read the newsgroups), leads to a moreimmediately interactive way of reading. Rather than simply reading thedocument and assuming that it might be difficult or time consuming tocontact the authors, e-mail now provides easy and speedy contact. Of course,this immediacy of contact does have a downside in that it now becomes alltoo easy to flame (to insult using e-mail) someone whose ideas or viewpointswe disagree with.

Despite this rapid pace of change, form has not become any less important toour documents. Indeed, it could be argued that it has become even more im-portant. You might note, for example, the increasingly widespread need tolearn how to use HyperText Markup Language (HTML) in order to structureand format electronic documents on the World Wide Web. HTML is simply asystem of tags that is used to format, link, and cross reference parts of anelectronic document on the Web so they can be read by people using differ-ent operating systems.

3.1.4. Rhetorical Form as Static

On the other hand, forms that have not changed for some time, that have be-come “form-ally” accepted in a discipline, are referred to as conventions. Andeach discipline has its own set of conventions (indeed, even within a disci-pline such as engineering, we find that there exist several overlapping sets ofconventions). Standard formatting conventions, such as how to reference in-formation sources, how to display equations, how to label tables and figures,etc., have developed over many decades in Engineering and serve importantpurposes in terms of helping readers to most easily process information.


79

However, because there are many subtle differences between the conven-tions used (they vary from company to company and from engineering fieldto engineering field), and because some of these conventions are changingeven as we write this text, we cannot hope to provide you with the best wayto format your documents. In fact, that best or correct way to format a docu-ment is an illusory goal. No matter what formatting convention is proposed,someone will find an alternative approach that makes more sense in a spe-cific context.

The recent change from placing the glossary in an appendix at the end of adocument to placing it near the beginning of the document is a good exam-ple of how formatting conventions sensibly evolve. At some point, a writerobserved that placing the glossary at the end of a document does not alertthe reader to its existence soon enough. Although this problem was tradi-tionally overcome by bolding the first technical term in a report and placinga footnote next to it that told the reader about the existence of the glossary,placing the glossary in the prefatory pages of the report is more likely to en-sure the reader sees it. This approach also eliminates the necessity of foot-noting the technical term. And eliminating this footnote is itself useful interms of the appearance of documents that use footers (a repeated line of textat the bottom of a page throughout a document).

Given these realities, this chapter provides you with several generally usefulprinciples about formatting documents rather than attempting to provideyou with the correct approach. In addition, this chapter provide some exam-ples of the more common conventions used in engineering. The next chapterprovides information about the genres common in engineering as well as ex-amples of specific documents. In both cases, you need to weigh our sugges-tions against the needs and expectations of your readers.

As you consider the format of your documents, try to do so from the per-spective of the reader. Make things as easy as possible for the reader. Askyourself specific questions about the format. For example, if you are thereader, do you really want to read a document produced with an 8 point fontsize? Probably not. Extended reading of material using such a small fontwould quickly lead to eyestrain. 11 or 12 point is usually a more appropriatechoice.

You will also need to develop an eye for the appearance of your document.In particular, it is important that you examine your document for the consis-tency of such things as heading levels, page numbering, and margins. Incon-sistency in the levels of headings, for example, can prove an irritating dis-traction to the reader. Whatever methods you use (font size, capitalization,underlining, bold face, or indenting), ensure that you are consistent through-out the document.

Initially, you will develop this eye for the appearance of your document byexamining the samples of well-formatted writing produced by others. How-ever, until you have thoroughly mastered formatting conventions, westrongly recommend that you print a rough draft of your document in orderto see how it actually appears and to edit for consistency.


80

Eventually, WYSIWYG (What You See Is What You Get) technology will beperfected and you will be able to do most of your format editing on-screen.But until then, a paper copy remains essential. This text, by the way, wasproduced in precisely this fashion. Formatting corrections were done on pa-per copies.

3.1.5. Mastering the Technology

The task of formatting your documents can be greatly simplified if youspend some time learning how to correctly operate the word processing andgraphics software as well as the printers and photocopiers that you use. Weencourage you to enroll in one of the many word processing workshops of-ten offered by most universities. And, if you do not already have one, obtaina good manual for your word processing package.

Whatever word processing package you choose to use, we strongly recom-mend that you spend some time learning how to use styles and templates. Theadvantages of using styles rather than directly formatting your documentsare threefold:

• Styles ensure that your documents will have a consistent appearancein terms of headings, captions, paragraph spacing, fonts, etc. Thischaracteristic is particularly important when writing long documentsor when writing collaboratively.

• Styles make changing the format of a document relatively easy. Thischaracteristic is especially useful when a document goes through sev-eral iterations or editions.

• Styles save time by enabling the use of speed formatting keys, byeliminating the need to constantly reconsider what format had beenapplied previously, and by allowing for the automatic generation oftables of contents. This characteristic is particularly helpful whenworking on long complex documents.

A style is simply any paragraph formatting that you use repeatedly through-out a document. For example, when we wrote this text as a handbook for ourstudents several years ago, the items in the bulleted list immediately abovethis paragraph had a style with the name, List 1, associated with them. Thisparticular style had a set of characteristics which we defined prior to begin-ning work on the handbook: 11 point, Book Antiqua font, flush left margin,indented 1 inch, hanging indent ¼ inch, 13 point line spacing, andwidow/orphan control. Indeed, that handbook had 31 distinct styles associ-ated with it, covering everything from the appearance of the basic paragraphformat to the appearance of the table of contents. Figure 11 provides a screencapture of the “Style Dialogue Box” for Microsoft Word 7.0 for Windows 95.


81

Figure 11: Style Dialogue Box (Microsoft Word 7.0)

Because the handbook was about 200 pages in length and was co-authored,consistency was particularly difficult to maintain and would have beennearly impossible if we had simply formatted the document directly. By as-signing styles to the various paragraph formats throughout the handbook,we ensured that the handbook was formatted consistently. Moreover, by de-fining a series of styles and then saving those styles as a template called hand-book.dot, we were also able to ensure that all subsequent handbooks followedthe same format.

As well as ensuring consistency, the use of styles enabled us to make globalformatting changes from edition to edition as we improved the format of thehandbooks. For example, our paragraphs were one inch wider in a prior edi-tion. But because we wanted our students to make marginal notes, we de-cided to increase the size of the margins by decreasing the width of theparagraphs.

This change was easily accomplished by modifying the format of the stylecalled Body. Simply making this one modification resulted in a consistentchange to the format of most paragraphs in the handbook. If we had not hadstyles associated with the document, we would have had to go through theentire document and change each paragraph individually – a time consum-ing and haphazard process.

To save even more time, we assigned speed keys to the various styles so wecould apply them to any paragraph simply by typing a few letters. For ex-ample, we applied the Body style simply by typing Alt-B. Moreover, by usingvarious built in heading levels, we were able to have our word processorautomatically generate and update the table of contents, which represented asignificant time saving compared to manually compiling the table of con-tents. This approach was also more accurate than if we had manually lookedup each page number before entering it in the table of contents.

However this last point, that of using the built in heading levels, is worthconsidering carefully as it reveals one potential risk to employing styles. Donot simply accept the default styles that your word processor proposes for


82

headings (or for that matter, for anything else). Modify them so they meetyour overall goals for the appearance of the document.

For example, the default heading styles used UPPER CASE and underliningfor several of their levels. We intentionally wanted to avoid capitalization be-cause text written in all upper case is more difficult to read than text inmixed upper and lower case. We also wanted to avoid underlining becausewe disliked the way that the line cuts off the descenders on letters like g, j, p,q, and y.

Although the details of how to set up styles vary from program to program,and thus will not be discussed here, these techniques are worth masteringbecause they can greatly enhance your proficiency and consistency. Onceyou have produced several different document types, created the necessarystyle sheets, and defined your speed formatting keys, it becomes a simplematter of applying these styles to new documents.

In other words, you will need to expend some time and effort to set up yourbasic formats, but all subsequent documents can be produced quite easily,and in the long run you will save time. It is for this reason that we sostrongly recommend you read the manual for your word processor, payingparticular attention to the specifics about styles, templates, speed keys, auto-numbering, etc. The long-term time savings will prove substantial and arewell worth the effort.

3.2. Writing to InformIf your goal is to inform, you must ensure that you provide readers with allessential information and yet avoid overburdening them with too much de-tail or with information not directly related to your purpose. As technicalwriters you will be constantly challenged to keep this delicate balance be-tween too much and too little information. To ensure that you maintain thisbalance, state your purpose in a sentence. Write it down; keep it in mind asyou plan; refer to it whenever you are uncertain about including a point; andread it over before you begin revising.

Keeping your purpose in mind as you plan, write, and revise your work willhelp you judge what information to include. If, for instance, your task in-volves writing a quick and dirty manual for first-time users of an oscillo-scope, your primary goal is to provide the basic information necessary to op-erate this device. Although you may know a great deal about the innerworkings of an oscilloscope and believe that your readers will find what youhave to say interesting, such information is inappropriate given your goal.

Considering how your information will be used and by whom will also helpyou determine what information to include (or exclude) and suggest how toorganize it. (You cannot separate considerations of audience and purpose.They always overlap in significant ways.) To meet the needs of your readers,you must keep those readers in mind as you plan, write, and revise. If, forinstance, you keep the novice user in mind as you work on the oscilloscope


83

manual, you will recognize the need to define any terms which may be newto your readers, to explain set-up and operation procedures in a step-by-stepfashion, and to provide appropriate visual aids.

3.2.1. Readers and Information Processing

Technical and professional writing should convey information as clearly andconcisely as possible. The best writers write with such clarity and simplicitythat their readers are able to focus attention so completely on the ideas pre-sented that they often fail to notice the writer’s style or the format of thedocument. Your goal, then, is to develop a style and format which allowsyou to present complex ideas simply and concisely. If you have developed ahabit of using big words and/or of writing long, complex sentences, thenyou should pay special attention to your style. If you have not consideredhow the format or organization of your document helps or hinders thereader, then you need to reconsider the impact of form.

Readers are not simply passive recipients of the content presented by texts;instead, they actively construct meaning from the words, phrases, sentencesand paragraphs which make up those texts. The meanings that you intend tocommunicate by way of a text are never identical with the meanings that areader constructs from the text. Each individual comes to a text with aunique set of beliefs, ideas, and experiences which derive from that individ-ual’s particular social and cultural background. This uniqueness guaranteesthat communication will never be 100% effective. At the same time, however,we can and do communicate effectively.

In general, readers construct the meaning of texts based upon a variety ofstructural and rhetorical expectations about how texts will be organized.When writers present information and structure their sentences and para-graphs in ways that anticipate and fulfill these expectations, they increasethe chances of communicating effectively with the reader. On the other hand,when writers violate the reader’s expectations, they increase the likelihoodthat the reader will misinterpret the intended meaning of the text.

A useful distinction we can draw here is between what has been calledreader-centered prose and writer-centered prose. Reader-centered writers con-sider how readers cognitively process the information in a text and are cen-trally concerned with increasing the reader’s comprehension. Writer-cen-tered writers, on the other hand, focus on the subject at hand and are cen-trally concerned with analyzing or describing the material so that they under-stand what they have written. Given the importance of readers, being writercentered is sure to cause problems.

Writing reader-centered prose requires close attention to various stylistic is-sues such as order, coherence, clarity, and conciseness and to various issuesof form such as organization, paragraphing, and format. Attending to theseissues, in turn, requires that you consider how to deal with such problems asjargon, nominalizations, passives, connections, punctuation, headings, gen-eralizations, fonts, justification, etc.


84

To the degree that you consider how these issues affect the reader, you in-crease the reader’s potential comprehension of the material. To the degreethat you ignore how those things affect the reader, you risk failing to com-municate. Figure 12 provides a graphical representation of the differencesbetween writing that is reader-centered and writing that is writer-centered.

Figure 12: How Style and Form Affect Communication

Of course, what counts as a readable style is a relative matter which mustalso be judged in terms of the specific audience for whom the document iswritten. For instance, a report which contains a great deal of technical jargonmay be read easily by someone who works in the same field as the authorwhile being virtually meaningless to someone outside that field. By the sametoken, a passage which seems terribly dense to someone with limited exper-tise might seem quite clear to an expert in the field. In other words, thejudgments you make concerning style and form depend upon who will readyour work.

Moreover, considerations about the reader and considerations about theaudience can sometime conflict. In scientific and technical writing, this con-flict is perhaps nowhere more evident than when deciding whether to usethe active voice and verb-based style (“We completed analyzing the data”) orthe more traditional passive voice and noun-based style (“Our analysis of thedata was completed”). Although the active voice and verb-based style are in-herently easier for the reader to understand than the passive voice and noun-based style, some scientists and engineers resist making this change, and soyou must consider the preferences of your readers into to determine whatstyle is most appropriate for a given situation.

In part, this preference for passive voice and a noun-based style makes sensebecause the traditional style creates the impression of objectivity, and many


85

scientists and engineers recognize that their audience will respond more fa-vorably to this apparent objectivity. At the same time, however, some of theresistance is simply resistance to change.

Although many specific details of style and form affect readers’ comprehen-sion, employing the following eight cognitive principles carries you a longway toward assisting your readers:

• Minimize memory load• Create order• Connect the new with the known• Provide general frameworks• Repeat important concepts• Employ graphics• Keep it simple• Eliminate cognitive interference

3.2.1.1. Minimize Memory Load

Human short term memory has very clear limits in terms of the number ofitems that can be easily retained in memory. This limit, sometimes referredto as the “magic number” is 7±2 items. In other words, some individuals willbe able to retain as many as 9 items in short term memory while others willbe able to retain as few as 5 items.

This memory limitation is the reason why telephone numbers in NorthAmerica are limited to seven digits, for example. Most people can remembera number that they have looked up in the phone book long enough to dialthe number (if you frequently fail to remember the number and must look itup again, perhaps your short term memory is closer to the lower limit). Fur-ther, you will note that North American telephone numbers are broken into2 chunks of information (3 chunks if the area code is included): (123) 456-7890. By breaking the number into smaller units of information, the numberbecomes even easier to remember.

Because reading complex technical materials already poses a heavy burdenon short term memory, you would be wise to minimize the memory loadthat the style and form of your writing further impose upon the reader.Consider for example, the following title:

“Mixed Analog/Digital Integrated Circuit Product Delivery ProcessBenchmarking.”

By stringing together 9 nouns, and thus overburdening the reader’s shortterm memory, the author of this title has made it very difficult for the readerto remember the information.

The title, on the other hand, can be made much easier to remember by usingprepositions and verbs to break up the noun string:


86

“Benchmarking the Product Delivery Process for Mixed Analog/ DigitalIntegrated Circuits.”

Although the revised title is 2 words longer, most people find it much easierto remember because the words have been grouped into 3 units: Benchmark-ing (verb), the Product Delivery Process (short noun string), for Mixed Ana-log/Digital Integrated Circuits (prepositional phrase).

In terms of style, you can minimize memory load by avoiding long strings ofnouns or prepositional phrases and by ensuring that lists are in parallel.Consider, for example, the following conclusion to a persuasive report:

The major considerations for review are as follows:• emphasize team member participation in planning and manage-

ment of each project;• provide formal project management training to all members of

the project group;• emphasize team building;• introduce an effective bid response system;• balanced resource planning;• lateral communications between functional departments;• marketing to solidify commercial specifications before commit-

ment to build;• increase the involvement of senior management in the project

process and the coordination of the functional departments.

In part, the difficulty with the above example is that the list is not properlyparallel (the first 4 items and the last item begin with verbs while the re-maining 3 items begin with adjectives or nouns). Yet we know that items in alist are inherently easier to remember when they are written in parallel (i.e.,all verbs or all nouns).

However, the stylistic problem with the above example is probably of lessimportance than is the problem with the form of the list. By simply listingthe 8 points in no particular order, the writer has almost certainly assuredthat the reader will find it difficult to sort out the most important points fromthe less important. Or worse, the reader may simply fail to remember any ofthe points and thus may not implement any of them.

By grouping the 8 points into sub-categories, the writer would minimize thememory load upon the reader and thereby ensure that the reader is ade-quately informed (and also more likely to be persuaded). Note how the fol-lowing list resolves the problems with the first list by dividing the informa-tion into sub-categories and by using parallel structure:


87

The major considerations for review are as follows: 1. Teamwork

• emphasize team member participation in planning andmanagement of each project

• encourage team building• increase lateral communications between functional

departments

2. Coordination• develop balanced resource planning• require marketing to solidify commercial specifications be-

fore commitment to build• increase the involvement of senior management in the

project process and the coordination of the functionaldepartments

3. Training• provide formal project management training to all mem-

bers of the project group• develop an effective bid response system

As should be apparent, writers can easily minimize the memory load im-posed by the form of a list simply by grouping related items.

3.2.1.2. Create Order

One of the most basic characteristics of the human mind is its need to find orcreate some sort of order in the encounter with reality. Although the ap-proach to organizing information varies somewhat from person to person,depending upon our particular personal, social and cultural background,when presented with information, we all seek to order or categorize it. Con-sider, for example, the following list of related items:

• a paper clip• a straight pin• a nail• a bobby pin• a staple• a cotter pin

What do these items have in common? Well, one possible organizing princi-ple is that they are all made of metal (composition). Or we might point outthat they are all the sorts of things typically found in a “junk” drawer(location). Or perhaps we might suggest that they are all used as fasteners(function).

When presented with apparent disorder, we strive to create some form of or-der. Unfortunately, the particular order that the reader creates may differfrom the order that you, as the writer, intended. To minimize the possibilityof misunderstanding, the writer must present information in a way that


88

clearly indicates to the reader the intended order, connection, and impor-tance of the information presented to the reader.

In terms of form, consider whether or not you have appropriately organizedyour document. You might, for example, consider using one of the commonpatterns of organization outlined in Table 4 to structure your entire docu-ment or to organize particular sections and even paragraphs.

Pattern DescriptionChronological Sequence of events through time, as for describ-

ing a process.Spatial According to physical relationships, as for de-

scribing an object.Comparison/Contrast Explanation of similarities and differences, as for

comparing old and new designs.Order of importance From most important to least important, as de-

termined by audience and purpose.Problem solving Explanation of problem, method, and solution

followed by recommendations.General to specific A general point followed by a more detailed ex-

planation and/or specific examples.

Table 4: Patterns of Organization

One way to ensure that your document reflects the pattern of organizationthat you intend and clearly communicates that pattern to the reader is toprovide appropriately descriptive headings and subheadings. You shouldalso ensure that you have appropriately organized (in terms of importance,time, etc.) any lists that you have provided. We suggest that you employ thefollowing strategies when creating lists:

• Ensure that all items in a list have something in common.• Try to restrict lists to no more than 5 points (if you have more than

five points, break the list using sub-headings).• Make lists grammatically parallel when possible (i.e., they should ei-

ther all start with verbs or all start with nouns).• Use bullets (or another symbol) when the items are of equal impor-

tance; use numbers to indicate priority, step-by-step instructions, ororder of importance.

In terms of the style of text, you can help communicate the intended order ofyour ideas by using words such as first, second, before, after, then etc. In addi-tion, you should carefully consider the order of instructions within a sen-tence. This point is particularly important should you ever find yourself re-quired to write a user’s manual or procedural instructions. Consider, for ex-ample, the possible consequences of the following instruction which tries toexplain how to bold some text on a word processor using short-cut keys:

“To Bold the selected text, press ‘B’ while holding down the ‘Alt’ key.”


89

If the new computer user did not read the complete sentence, but insteadsimply followed the instructions in the order given, he or she would end upreplacing the selected text with a line of B’s:

“bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb”

On the other hand, if the sentence were rewritten as follows, the novicewould be less likely to make this mistake:

“To Bold the selected text, first hold down the ‘Alt’ key and then press‘B’.”

3.2.1.3. Connect the New with the Known

We learn most readily by connecting new information with things that we al-ready know. In terms of form, employing certain traditional forms providesthe reader with familiar contexts for learning new things. Using conventionalfor memos, proposals, specifications, manuals, and reports therefore helpsreaders assimilate new information. The more complex the new informationthat you must communicate to the reader, the more important standardforms become.

As well as using conventional forms, you also need to consider the conven-tional ways of organizing documents. The following, for example, outlinesthe conventional way of organizing a report:

1. Prefatory Pagesa) Title Pageb) Abstract or Executive Summaryc) Table of Contentsd) List of Figurese) List of Tablesf) (Glossary)

2. Body of Documenta) Introductionb) Backgroundc) Discussiond) Recommendationse) Conclusion

3. Appended Pages:a) Glossaryb) Technical Materialsc) References

Note that in the above list, the glossary (list of defined terms) appears twice.The reason for this is that the convention for where the glossary is placed ina report seems to be changing. In the past, the glossary was generallyincluded as an appendix. More recently, however, the glossary is beingplaced in the prefatory pages.


90

Not all readers check the table of contents to see if there is a glossary some-where in the report, but most will flip through the prefatory section and findthe glossary. Knowing immediately that there is a glossary for the report en-ables readers to remove (or copy) it so they can easily refer to it when read-ing the report. Placing the glossary near the end of the report ensures somereaders will not discover it exists until long after they needed it.

While you should generally use conventional forms and organize them inconventional ways simply in the interests of assisting the reader, you shouldalso remain aware that conventional forms restrict the kinds of informationthat can be communicated. Radically new ideas sometimes require radicallynew forms. Consider, for example, how some types of on-line user’smanuals are designed. The use of buttons (or other types of links) embeddedin the text, enable readers to move to glossaries, related subtopics, etc.without the need to read the entire document or spend time searchingthrough an index. Figure 13 provides an early example of this type of on-lineuser’s manual:

Figure 13: Buttons in On-Line Documentation

Although, on the face of it, this idea may no longer seem especially radical,these new types of user’s manuals have recognized a reality that more tradi-tional manuals ignore: users generally do not read the entire manual; insteadthey prefer to get started and then seek help as they need it. This form ofuser’s manual is radical, at least so far as it considers how users actually readmanuals rather than assuming that readers consider everything the authorhas written. They don’t.

In terms of style, we will be most successful in communicating new informa-tion to the reader if we ensure that new or important information is placed atthe end of most sentences while old or less important information is placedat the beginning (e.g., “Although in the past we have approached the problem inthat fashion, we now deal with the problem in this way” rather than “We now dealwith the problem in this way even though in the past we have approached the prob-lem in that fashion”).

Although placing important or new information at the end of sentences mayseem counter-intuitive, in fact, the ends of sentences carry more emphasisthan do the beginnings of sentences. And readers, consequently, expect tofind the important information in that location. Unfortunately, many writersfail to recognize that reality, and in their excitement to communicate theirideas, sometimes end up placing the important information at thebeginnings of sentences. In this case, the way that the writers construct theirsentences conflicts with the reader’s expectations. We explain this pointfurther in the chapter about style.


91

3.2.1.4. Provide General Frameworks

We know that readers understand material best when it is presented in cer-tain ways. Studies in reading comprehension indicate that information ismost effectively processed and retained when the reader has a general over-view prior to reading the more detailed material within the report.

Consider, for example, the value of an abstract that clearly and conciselysummarizes the information in a document. By providing a general frame-work in which to fit the rest of the information contained within the report,the abstract assists the reader’s comprehension. This, by the way, is a goodreason for reading the table of contents and the chapter summaries of a text-book prior to reading the chapters (and it is for that reason that we have pro-vided you with a brief chapter summary at the beginning of each chapter inthis text). Abstracts and executive summaries are not simply useless re-quirements of format dreamed up by writing teachers; in fact, they functionto increase the comprehension of the reader (among other things).

The same is true of the introduction to a report; it helps frame the informa-tion contained within the rest of the report, thereby increasing the readers’comprehension. Perhaps this function accounts for the insistence by so manycomposition teachers that a clear topic statement be placed within the firstparagraph of an essay. In a sense, abstracts and introductions function likerough maps: by knowing ahead of time where we are going, we can getthere with greater ease.

Consider, for example, giving someone directions about how to find yourhouse in a large city. If you were to give them the following specific instruc-tions they would probably get lost:

First, go 8 miles east. Turn right at the light. Then go 1.6 miles south andturn left at the light. Then go 7.8 miles east and turn left. Go one block,turn right. Go two more blocks and turn right at the first set of lights.Then turn left at the next four-way stop sign. Go one block, turn left. Ilive in the second apartment block from the corner.

Your instructions could be given more efficiently and would be easier to fol-low if you provided a general framework first and omitted any unnecessarydetails:

Do you know where the Washington General Hospital is? You do? Good.Do you know where the McDonald’s restaurant is across from the mainentrance? Great! I live in the apartment block behind it.

The general framework which is provided – “Washington General Hospital”– makes the specific information which follows it – “ McDonald’s” – morecomprehensible.

Of course, if the person doesn’t know where the Washington General Hos-pital is, then you must provide an even more general framework. The gener-ality of the framework which must be provided is directly related to the


92

reader’s depth of knowledge about the topic. When writing for an audienceof non-specialists you should provide frameworks that are more generalthan when writing for an audience comprised of specialists.

3.2.1.5. Repeat Important Concepts

Consider the following memorable words:

I have a dream that one day this nation will rise up and live out the truemeaning of its creed: “We hold these truths to be self-evident: that allmen are created equal.” I have a dream that one day on the red hills ofGeorgia the sons of former slaves and the sons of former slave ownerswill be able to sit down together at a table of brotherhood. I have a dreamthat one day even the state of Mississippi, a desert state, sweltering withthe heat of injustice and oppression, will be transformed into an oasis offreedom and justice. I have a dream that my four children will one daylive in a nation where they will not be judged by the color of their skinbut by the content of their character. I have a dream today.

Most people know instantly who said the words (and some can recite thelines from memory).17

The parallel structure demonstrated in the above example is a particularlypowerful way to communicate information because the rhythm created bythe repeated words, I have a dream, help the reader remember the ideas in thetext. Indeed, many speakers make extensive use of parallelism because of itsdramatic impact upon the memory of the audience. Although you are un-likely to make great use of this kind of parallelism in most technical docu-ments, you may occasionally find it helpful if you are ever asked to writepromotional literature for a product or to give a motivational speech.

Beyond that kind of repetition, however, we know that merely repeating keypoints or words within a document (or an oral presentation, for that matter)can substantially increase the amount of information which the reader (orlistener) will remember. The power of repetition to enhance memory is per-haps most clearly demonstrated by considering how people most effectivelystudy. Those individuals who review the key concepts of a subject over thecourse of a semester as well as reviewing them immediately prior to theexam, generally perform most successfully on the exam. The conclusion of areport serves a similar function. By recapitulating the most important infor-mation within the report, you help the reader remember the material.

A well-written report will generally repeat the most important points inthree places: once in the introduction, once in the body of the report, and fi-nally, once in the conclusion. There is a certain truth to the advice aboutspeaking which suggests you should “Tell them what you are going to say; 17 And, for those who are unfamiliar with this quotation, the author is Martin Luther King Jr.

(Speech, Steps of the Lincoln Memorial, August 28, 1963). The source for this quote was thewebsite maintained by the National Civil Rights Museum in Memphis Tennessee(www.mecca.org/~crights/dream.html).


93

say it to them; and then tell them what you have said.” However, this doesnot mean that you should simply parrot the same information in preciselythe same words each time (in fact, if you do so, you will probably end upboring your audience). As it happens, memory retention is increased if youreiterate the same information in slightly different ways.

Moreover, repeating the information in different ways has the potential tofurther increase the reader’s comprehension. Because, as previously men-tioned, we comprehend new information best when we can connect it withthings we already know, the more different ways you communicate the in-formation, the more likely you are to provide opportunities for the reader toconnect it to something already known. and this, by the way, is the reasonthat similes and metaphors are such powerful tools for explaining things –they demonstrate a similarity between something with which we are familiarand something we do not yet understand.

Transitions at the beginning of paragraphs, sections, and chapters can alsoremind the reader of a previous point, drawing their attention to importantinformation while setting a context for what is to come next. Transitions thatremind the reader of the purpose at hand are particularly important follow-ing a detailed discussion of one point when the reader may need remindingof the context for the next point.

3.2.1.6. Employ Graphics

Like repetition, the judicious use of tables and figures can help the readermore easily comprehend and remember information because you do some ofthe work for the reader by integrating the information into an easily graspedwhole. We are all familiar with the adage that “a picture is worth a thousandwords.” Actually, a picture is worth far more than that. An accurately la-beled figure can mean the difference between total incomprehension on thepart of the reader and absolute clarity. And we tend to remember best thingsthat are shown to us rather than simply explained to us. For the significantnumbers of technically oriented people who are visually oriented, graphicsare particularly helpful. Graphics are especially important for readers whenyou are writing about extremely complex or highly technical subjects.

Perhaps some of the best examples of how graphics can be used effectivelyare to be found in well written user’s manuals. You might, for example, lookat some of the user’s manuals provided by Hewlett Packard Ltd. for settingup and maintaining laser printers. In this particular case, most people findthey can do routine tasks, such as changing toner cartridges, simply by fol-lowing the diagrams. The text that accompanies the diagrams seems almostsuperfluous.

However, when you use figures in your reports, you must accurately labelthem and ensure they are good quality reproductions. A figure that is diffi-cult to understand or hard to read does not help the reader; it simply wastestheir time. Similarly, you must place your figures as close as possible to theplace in the text where you mention them, either on the same page or on the


94

page immediately following the reference (and never place a figure before thetextual reference). Few things are more frustrating for a reader than being re-quired to search for a figure (or worse, encountering a figure not mentionedin the text).

In terms of style, the prudent use of similes (e.g., something is like somethingelse), has a similar effect to that of graphics because similes allow readers tovisualize new, often abstract, information in terms of already known, moreconcrete, information. Consider for example, trying to explain how to deletea file to someone who is familiar with Macintosh computers how to use aDOS based system. If you were to write the instruction, you might use a sim-ile as follows:

“Typing “DEL filename.ext” in DOS is like dragging that file to the gar-bage can”

On the other hand, you might simply use something like Figure 14 to com-municate the same information.

Figure 14: Using Figures to Explain Concepts

3.2.1.7. Keep It Simple

Although it seems an obvious point, it bears repeating that readers will findit easiest to comprehend what you are writing about if you keep it simple. Ofcourse, you must also be careful to not over-simplify or some of your audi-ence may feel you are talking down to them, or worse, may dismiss yourideas as inconsequential. In this regard, Einstein had some advice for scien-tists which also applies to engineers and technical writers: keep your ideas assimple as they can be, but no simpler. As with so many aspects of writing,finding the appropriate level of detail and complexity requires careful atten-tion to audience.

When writing to technical specialists rather than non-specialists, you can, ofcourse, increase the level of detail and complexity that you employ. How-ever, at many points in your career, you can expect to face situations inwhich you must write reports to mixed audiences comprised of both spe-cialists and non-specialists. This particular type of audience can pose a con-siderable challenge.


95

If you include in the body of your report all the technical information neededto meet the needs of the specialists, you will probably confuse the non-spe-cialists who will read your report. On the other hand, if you omit all thetechnical details in order to meet the needs of the non-specialists, then youwill probably fail to provide sufficient information for the specialists. Oneway to resolve this problem, and meet the needs of both audiences, is toplace the technical specifications and analyses in an appendix, (or, in somecases, in endnotes or footnotes).

Nevertheless, in some circumstances the entire report may be so technical innature that it becomes impractical to use appendices (i.e., the entire reportwould end up as an appendix). Or it may be necessary to communicate someof the technical information to the non-specialist. In these cases, you wouldbe wise to use more graphics and concrete examples. And also ensure thatyou provide sufficient general information so that the non-specialist canplace the technical details in context.

In addition, you may also want to use slightly shorter sentences than usualand restrict your use of jargon. At the very least, clearly explain anytechnical terms that are unavoidable by including a glossary which defines(in non-technical language) the terms you are using. Although the reportmay still be difficult reading for non-specialists, they can consult the glossaryfor clarification as they work their way through the document.

3.2.1.8. Eliminate Cognitive Interference

Another way in which form and style can assist the reader’s understandingof information is by eliminating cognitive interference. By cognitive interference,we mean the way in which certain elements of poor format or style can inter-fere with the reader’s ability (or willingness) to focus upon the material inthe report. We know that readers are best able to comprehend and retain in-formation when they can focus solely upon the ideas presented by a reportand are not distracted by problems with spelling, grammar, style, or format.Consider, for example, what happens as you try to read the text in Figure 15:

This paragraph is set in 4 point text and is therefore very difficult to read. You have probably all had the experience of reading apoor quality photocopy where you were required to focus so intently upon deciphering the individual letters and words that itbecame very difficult to put together the meaning of the text. Because we read most efficiently by recognizing the patterns of thewords, when you interfere with this by using a very small font, by using a sans serif font, or by producing poor quality documentsin other ways (i.e., dot-matrix printing, poor quality copying), you slow down your readers. Readers who are impeded in this waybecome frustrated and experience cognitive interference. In extreme cases, they give up.

Figure 15: Example of Cognitive Interference

If, like most readers, you found it difficult to read because of the small font,then you have experienced cognitive interference. Readers are both less ableand less willing to spend time comprehending information when they aredistracted either by irrelevant and sometimes excessively detailed material orby problems caused primarily by poor format (i.e., difficulties finding spe-


96

cific information because of a lack of pagination or difficulties reading thereport due to poor quality printing or copying). In terms of style, frequentspelling or grammatical errors will also interfere with the reader’s focusupon information. A high level of cognitive interference will lead to a highlevel of frustration, which in turn, will lead to a low level of comprehension.

Readers should be able to take for granted that you will provide proper mar-gins, headings, pagination, print quality, figure labeling, etc. Moreover,readers should also be able to assume that you will have spell-checked yourdocument and will have carefully edited it for typographical and grammati-cal problems.

Finally, ensure you maintain a consistent format throughout your document.Once the reader becomes accustomed to certain conventions of format (aswell as style and spelling), they will find it disconcerting to switch to an-other. You minimize the cognitive interference experienced when consistent.


97

3.3. General Principles of FormatAs you go about formatting your work, you need to attend to a wide rangeof issues. In particular, you should pay special attention to such things aswhite space, organization, graphical elements, and referencing conventions.

3.3.1. White Space

Generally, when most writers think about format, they only consider the textof the document and not the white space which surrounds that text. How-ever, if you are to generate the best possible format for any particular docu-ment, you must learn to pay careful attention to the areas where you do nothave text as well as those where you do. The white space in a documentserves several important functions. Perhaps the most obvious function ofwhite space is to allow instructors (and sometimes editors) to make com-ments. For this reason, many instructors insist that you provide adequatemargins (1 to 1¼ inches) and double space your documents.

A more important function of white space is that it enables readers to clearlysee what information belongs together. White space can be used to separatevarious elements of a report, such as paragraphs, sections, and figures.

For example, you might place ½ inch of white space between the end of onesection and the next heading, but only ¼ inch of white space between thatheading and the following section. This sort of spacing helps the readeridentify that the heading belongs with the following text. Figure 16 contrastsa text with poorly spaced headings (on the left) with one that properlyspaces headings (on the right).

Figure 16: Spatial Relationships between Headings and Text


98

Careful spacing is especially important with figures and tables. If the figurelabel is located an equal distance between the figure and the text, at firstglance it is difficult to tell whether the label is, in fact, a label or perhaps anew heading. The label should be located closer to the figure than to the text.The same is true for the label you use with a table. Figure 17 contrasts a textwith properly spaced figure labels (on the right) with a text that has improp-erly spaced figure labels (on the left).

Figure 17: Spatial Relationship between Figure Labels and Text

Further, should you ever need to place two figures on a single page, ensureyou space them so the reader will have no difficulty identifying the first labelas belonging with the first illustration. If the label is an equal distance be-tween the two figures, the reader will momentarily be confused about whichfigure the label identifies. Obviously, the reader will eventually see the sec-ond label and solve the problem.

But remember, we are suggesting that you should use your format to makethings easy for the reader. Even a momentary confusion causes the reader tolose their focus upon the information you are communicating. As mentionedearlier, proper format is more or less invisible.

A final important way that white space functions is by rather subtly indicat-ing to the reader the degree of complexity of the information containedwithin the document. When readers first glance at documents with hightextual densities (i.e., little white space), they often tend to assume that theinformation being communicated is complex or difficult to understand. Ex-cessively long paragraphs, by the way, communicate the same impression.


99

Consider, for example, the differences between books written for childrenversus books written for adults. Children’s books have wider margins, widerspaces between lines, larger type, shorter paragraphs, shorter sentences, andmore illustrations – overall more white space – than do books written for anadult audience. As the children become older, and thus more proficient atprocessing information, the textual density increases in relation to their age.

The key point here is that most of us have learned to associate textualdensity with difficulty. The degree to which the reader’s presumption thatinformation is difficult or complex actually interferes with comprehension isa question still under investigation, but it seems reasonable to assume that itdoes have some effect.

Depending upon your audience, you might wish to consider varying thetextual density of your report. When writing for the non-specialist, it isprobably appropriate to increase the amount of white space in your docu-ments by shortening your paragraphs, including more figures, and using in-dented lists more frequently. You may well increase your reader’s compre-hension (or at least their willingness to read the material). At the same time,be careful that you do not over-simplify your document because you mayunwittingly irritate your audience by appearing to “talk down” to them.

Further, you should exercise some caution when shortening your para-graphs. One sentence paragraphs are usually not a good idea (althoughwhen used occasionally, one sentence paragraphs can prove an effective formof emphasis). An average paragraph length of three to five sentences may beappropriate for the non-specialist audience while an average paragraphlength of five to seven sentences may be more appropriate for the specialistaudience. And for any audience, variety in your sentence lengths and para-graph lengths will help maintain interest.

Figure 18 provides a graphic example of how the amount of white space in atext influences the perception of complexity. If you were faced with readingtexts with those differing amounts of white space, which would you prefer?

Figure 18: Texts with Contrasting Amounts of White Space


100

3.3.1.1. Print Quality

The quality of the print you use in your documents can have a major impactupon the willingness of the reader to read them closely. We have probablyall had the unpleasant experience of trying to read a photocopy that was sofaded we had to strain to decipher the individual words. Because we mustdevote so much effort to translating the individual letters and words, wecannot pay sufficient attention to the ideas (if, in fact, we do not simply giveup in frustration). The more effort devoted to deciphering the print, the lesstime can be devoted to comprehending the information.

The quality of the print depends upon a number of factors: font size andtype, line spacing and justification, as well as the capability of your printerand the quality of your reproductions. We advise you to spend some timeconsidering how these factors will impact upon your readers.

There are many thousands of different fonts available, but not all of these areacceptable for use in technical documents. Table 5 provides a sample of somecommon fonts.

Table 5: Selected Examples of Fonts

Text (Serif) Headings (Sans Serif) Special PurposeTimes New Roman Arial CourierBook Antiqua Arial Narrow Lucida FaxPalatino Helvetica Zapf ChanceryCentury Schoolbook Helvetica Narrow Wedding TextBookman Old Style Avant Garde Caslon Open Face

To some degree, the choice of a font is a matter of personal preference. How-ever, it can also be a matter of readability and suitability to your rhetoricalpurpose. Obviously, using a font such as Wedding Text or Caslon Open Face ina technical document would be inappropriate. Both fonts are far too ornateand are best reserved for special uses such as signs or invitations.

In general, you should use serif fonts rather than sans serif (literally, withoutserifs) fonts for most of the text in technical documents, particularly lengthyones. Serifs are simply the small lines at the tops and bottoms of letters.Figure 19 enlarges the difference between a serif and sans serif font.

Figure 19: Detail of Serifs


101

The reason for avoiding sans serif fonts for the body of a document is that thelack of serifs in these fonts makes it more difficult for readers to recognizethe patterns of words when reading. This difficulty becomes especially ap-parent if the reader must read a lengthy document. Eye strain sometimes re-sults. By cutting off the lower half of the words, Figure 20 exaggerates howsans serif fonts interfere with character recognition.

Figure 20: Word Pattern Recognition for Sans Serif versus Serif Fonts

We suggest that you reserve sans serif fonts for the headings in documents.Even here, some caution is advisable: narrow sans serif fonts, such as ArialNarrow and Helvetica Narrow are more difficult to read than their uncom-pressed counterparts, Arial and Helvetica. Nevertheless, we occasionally usethe narrow fonts when space is quite limited (in the cells of a large spread-sheet, for example).

Yet issues of readability can be much less subtle than this. For instance,when we were originally producing this text as a handbook for our students,we chose to use a font called Book Antiqua for most of the text because itphotocopied better than the font called Times Roman and thus made the textmuch easier to read. For similar reasons, we generally use a font calledLucida Fax when sending Facsimiles (FAXes). Figure 21 compares severallines of text using these three fonts so you can more clearly see thedifferences. The font size in all cases is 10 point.

Lucida Fax is an easy to read font that issometimes used when sending FAXes.

Book Antiqua is an easy to read font that is some-times used for photocopied documents.

Times New Roman is a general purpose font that cansometimes be difficult to read.

Figure 21: Comparison of the Readability of Selected Fonts

As you may have noted in Figure 21, Lucida Fax is the largest and least com-pressed of the three fonts. Consequently, it works well when FAXing docu-ments to a machine that may not clearly reproduce smaller, more tightlycompressed fonts. Book Antique is intermediate in size, while Times Roman isthe smallest. In fact, because Times Roman is so small, we recommend thatyou do not use it for text at a size below 12 point. And in general, we suggestthat you use a font size of 11 or 12 points, although you might use smallersizes for footnotes (i.e., 8 or 9 point) and larger sizes for headings (i.e., 14, 18,and 22 point).


102

You would also be wise to not use italics or boldface for an entire document:reserve these font styles for special purposes such as indicating emphasis orcreating headings. Similarly, you should avoid using all upper case when-ever possible. The use of all upper case is less an issue with reports than it iswith overheads used for presentations.18 The problem with using all uppercase is that reading text formatted in all upper case is inherently slower thanreading text formatted in mixed upper and lower case. Figure 22 demon-strates the difficulty that can be caused for readers when all upper case isused.

TEXT FORMATTED USING ONLY UPPER CASE LETTERS ISMUCH MORE DIFFICULT TO READ THEN TEXT FORMATTEDUSING A MIXTURE OF UPPER AND LOWER CASE LETTERS.THIS DIFFICULTY OCCURS BECAUSE WE DO NOT READ VERYEFFICIENTLY LETTER BY LETTER. WE READ MOREEFFICIENTLY WHEN WE CAN RECOGNIZE THE PATTERNS OFWORDS AND THUS CAN READ WORD BY WORD. BECAUSEUPPER CASE LETTERS ARE ALL EVEN IN HEIGHT, WECANNOT USE PATTERN RECOGNITION, AND WE ARE FORCEDTO READ LETTER BY LETTER. THAT SLOWS US DOWN.

Figure 22: The Problem with Using Only Upper Case

Finally, another factor beyond readability may influence your choice of font:how modern the font looks. Although Courier was once popular (mainly dueto printer limitations), it is rarely used anymore because it has a decidedlyold-fashioned appearance. Today, Courier is almost exclusively limited tospecial purposes such as listings of program code. Similarly, some peoplefeel that Times Roman and Helvetica have been used for so many years thatthey also appear dated. You may want to remember that as you considerwhich font to use when preparing technical documents.

3.3.1.2. Paragraphing

As we have mentioned earlier, you need to determine how long to makeyour paragraphs based upon considerations of audience and purpose. Ingeneral, paragraph length in technical documents lies between three andseven sentences depending upon the expertise of your audience, the widthof the paragraphs, and whether you are single or double spacing thedocument. In addition, we advise that you avoid overusing one sentenceparagraphs because too many will lead to a lack of coherence. The occasionalone sentence paragraph, of course, can be an effective way to add emphasisto a point.

As well as considering the length of your paragraphs, you should also con-sider several other issues in relation to paragraphing: spacing between lines,dealing with orphaned lines, and indicating the beginning of a new para- 18 In fact, we know of one local company which insists that all overheads prepared for

presentations must only use upper case. Although the engineers who work for thecompany recognize that all upper case is more difficult to read, they nevertheless followthe practice. They probably shouldn’t.


103

graph. In general, we recommend that you double space documents writtenfor instructors or for anyone else who will review the document. The doublespacing permits reviewers to write comments between the lines which willfacilitate later editing of the document.

Final versions of reports, and documents such as letters and résumés, areusually single spaced. Yet even here you may want to consider the effect ofspacing. Using a technique called leading (pronounced ledding19) increasesthe readability of most text. With leading, you use a line spacing that is twopoints greater than the font size. For example, if your document uses a 12point font, you might set the line spacing to 14 points (Printers would de-scribe this as 12 on 14 spacing). The extra 2 points increases the space betweenlines and thus makes it somewhat easier for the reader to follow the text.

For many word processors, 2 point leading is the default setting, so mostdocuments tend to use that. Nevertheless, being aware of this practice can beuseful should you ever need to squeeze one or two extra lines into a shortdocument. Reducing the leading from 2 points to 1 or 1.5 points may allowyou to fit those extra few lines into the document. We do not recommend,however, that you totally eliminate leading (12 on 12 spacing) as the ascendersof some letters (b, d, f, h, k, l, and t) will run into the descenders of other letters(g, j, q, p, and y) from the line above.

You should also ensure that you do not orphan the first or last lines of yourparagraphs. An orphan is simply a single line from a paragraph that is iso-lated from the rest of the paragraph when the paragraph splits at a pagebreak. Although orphaned lines are visually distracting, they probably don’tinterfere with the reader’s comprehension. In any case, most wordprocessors allow you to set up paragraphs so orphaned lines are notpermitted (note that sometimes this setting is incorrectly calledWidow/Orphan Control20).

A final point to consider in relation to paragraphing relates to how youcommunicate a paragraph break to the reader. In most published work, thestart of a new paragraph is indicated by a small indent. For documents pro-duced using a word processor, however, there appear to be 2 competingconventions: using the small indent or leaving a blank line between para-graphs. Figure 23 shows the difference between the two differentconventions.

19 The term leading originates from the practice of placing strips of lead between rows of

characters during the early days of printing.20 A Widow has nothing to do with where a paragraph splits (as the authors of Microsoft Word

suggest), but rather refers to the hyphenation of the last word in a paragraph.


104

Figure 23: Alternative Paragraph Conventions

Although either convention can be considered correct, within some universi-ties the indent convention is more typically found in documents written forthe Humanities while the blank line convention is more typically found indocuments written for Engineering and the Sciences. Because the blank lineconvention is also becoming increasingly common in documents from thehigh technology industries, you may want to adopt it. Remember that theform you adopt for your documents rather subtly indicates yourmembership in a professional community. In other words, using a blank linerather than an indent may serve a persuasive function when working as anengineer.

In any event, you should probably avoid using both conventions at the sametime (if for no other reason than doing so is rather redundant). And ensurethat whichever convention you use, you maintain consistency throughoutthe document. Switching back and forth between the two conventions in asingle document could be rather disconcerting for your readers.

Finally, if you do choose to use the indent convention, you should ensurethat your indent is no larger than ¼ inch in length. Some people use a ½ inchindent (the default setting for tabs21). This larger space is a holdover from thedays of typewriters and early printers which used mono-spaced fonts (i.e.,each character took up the same width in a line of text – Courier is an exam-ple of a mono-spaced font). The larger space looked fine with these fonts.However, most modern word processors and printers use proportionallyspaced fonts (i.e., the spacing is adjusted depending upon the width of the

21 We suspect that the default setting for tabs has a lot to do with the continued use of ½ inch

indents. It is intrinsically much easier to simply use the tab rather than to set up aparagraph style that defines the paragraph indent as ¼ inch. We suggest that you learn touse styles so that you have much finer control over the appearance of your documents.


105

character – an i takes up less space than an m, for example). More than a ¼inch indent is excessive with proportionally spaced fonts.

3.3.1.3. Margins

In general, you should provide margins of at least 1 inch on all sides of yourdocument. However, in documents which are submitted to reviewers or in-structors, and upon which you expect comments to be written, they mayfind it helpful if you increase your margin to 1¼ inches. In somecircumstances, you may even want to increase one of the margins (usuallythe left one) to 2 or 2½ inches. This is the practice we followed when weinitially wrote this text as a handbook for our students. We left a wide leftmargin, in part to create a more visually appealing format, but mainly togive the students room to write comments during our lectures. This widermargin is sometimes known as the Scholar’s Margin.

3.3.1.3.1. Paragraph Justification

Our final point about white space involves considering whether to justifyyour text or to leave the right margin ragged. Figure 24 compares full justifi-cation with a ragged right margin.

Figure 24: Full Justification versus Ragged Right Margin

Readers find it easier to maintain their place in text with a ragged right mar-gin, so where comprehension is a key concern, avoid justifying your text.However, sometimes the neat appearance of justified text serves apersuasive function, and you may want an even margin. As with so many


106

issues, your choice depends upon the inter-related concerns of audience andpurpose.

In any case, you are well advised to avoid justifying text that is formatted innarrow columns. Justifying narrow columns of text frequently results in un-sightly wide gaps between the individual words (sometimes called Rivers ofWhite). Unfortunately, not justifying narrow columns often results in anoverly jagged right margin. To avoid this problem, we suggest you use thehyphenation option generally included with most word processing programs.

3.3.1.3.2. Hyphenation

Should you choose to use hyphenation to avoid an overly ragged right mar-gin, do not rely solely upon the automatic setting for hyphenation. Use themanual setting which allows you to review proposed changes or, at the veryleast, carefully proofread any text which has been automatically hyphenated.The following points indicate some of the issues to consider as you are hy-phenating documents:

• Do not hyphenate headings or subheadings.• Avoid hyphenating three or more lines in a row because excessive

hyphenation tends to slow down readers (much like justification) andcreates unsightly parallel lines at the ends of the lines.

• Do not hyphenate proper nouns (i.e., names of people and places) orcompound words (i.e., words that already have a hyphen in them).

• Avoid hyphenating the last word in a paragraph (sometimes definedas a widow).

• Ensure you have broken the word at the correct location dependingupon its grammatical context (i.e., pro-ject is a verb while proj-ect is anoun).

3.3.2. Organization

The organization of your documents is critical because most readers of tech-nical documents have certain expectations about how the document shouldbe structured. There are several issues that you should consider as you goabout organizing technical documents: the traditional sections for docu-ments, the headings used to communicate the document organization to thereader, the pagination of the document, the use of headers and footers, andthe inclusion of a table of contents and a list of figures and tables.

3.3.2.1. Sections

The following list presents a standard organization which suits a wide rangeof writing situations requiring formal research or technical reports. Note,however, that you may discover good reasons for using a somewhatdifferent format – good reasons created by the nature of your audience,purpose, or subject matter. For example, when you are writing a short report


107

(10-15 pages) for an audience that is quite familiar with your subject matter,you might consider writing a letter report. This type of report begins with thestandard salutation (Dear Ms. Smith:) and ends with the standard closing(Sincerely,). The letter report omits the prefatory pages and appended pages,and only provides the body of the report (which may or may not be dividedinto subsections). Module 2 provides an example of a letter report.

Although you will often not need all of them, the sections of a report areconventionally tenfold (in the following order):

1. Title Page2. Copyright Page or Revision History Page3. Executive Summary or Abstract4. Acknowledgments5. Table of Contents6. List of Figures and Tables7. Body of the Document8. Glossary (sometimes placed before the Body)9. References10. Technical Appendices

3.3.2.2. Headings

The formats for headings and subheadings vary from writer to writer andfrom company to company. Once on the job, you may find it necessary toadopt the particular format favored by your employer, but in the meantime,you can develop your own system – within certain limitations.

In your own reports, you can use any combination of numbering, indenta-tion, capitalization, boldfacing, font size, and underlining, as long as yourheadings clearly distinguish between levels and are consistent throughout.Do note, however, that underlining is decreasing in popularity as a methodfor indicating heading levels because it cuts off the descenders on certainlower case letters (g, j, q, p, and y). Figure 25 indicates the problem.

Figure 25: The Problem with Underlining Headings

And as we mentioned earlier, capitalization is also becoming less popularbecause reading text that is formatted in all upper case is more difficult thanreading text that is formatted in mixed upper and lower case.

In any event, you should also consider the following points as you createyour own headings.

• The format for headings and subheadings must clearly indicatewhether a particular heading introduces a major section, subsection,sub-subsection, or paragraph.

• Try to avoid using acronyms or abbreviations in headings.


108

• Headings should be as descriptive as possible (i.e., rather than justusing a heading such as Tungsten Carbide, which contains little infor-mation about the content of the section, you should add descriptivewords such as Failure Modes in Tungsten Carbide Impellers). Except forchapter headings, each heading should be followed by some text.

• Major section headings – or in the case of long reports, chapter head-ings – must begin on a new page.

• To create a subsection, you must be able to divide a larger sectioninto at least two parts (i.e., you should not have a single subsection).

• With the exception of paragraph headings followed by a period, omitall end punctuation except a question mark.

• Either capitalize the first letter of all major words in a heading (don’tcapitalize articles, prepositions, and conjunctions unless they are thefirst word in the heading) or capitalize only the first letter of the firstword in a heading.

• Proofread carefully to ensure that you have not inadvertently isolateda heading or sub-heading at the bottom of a page.

The best formats are as simple as possible while still clearly distinguishingamong the different heading levels. You should not, for example, find it nec-essary to bold, underline and capitalize a heading, or even to bold and un-derline it. Figure 26 illustrates one possible format for reports with four lev-els of headings.

1. Major Heading

1.1. Subheading 1

1.1.1. Sub-subheading 1

1.1.1.1. Paragraph Heading.

1.1.1.2. Paragraph Heading.

1.1.2. Sub-subheading 2

Figure 26: Accommodating Four Heading Levels


109

If you set up your headings as specific styles within your word processor,you will find it relatively easy to maintain consistency in your heading lev-els. Furthermore, you will be able to easily produce the table of contents.

3.3.2.3. Pagination

Page numbers are essential in lengthy reports and manuals as they helpreaders find specific topics mentioned in the table of contents. Yet even inshort reports that do not require a table of contents, you should always num-ber your pages. Keep in mind that documents are often photocopied for dis-tribution. Should the person doing the copying mix up the pages (and this iseasy to do), they may well reorder the pages incorrectly if page numbers arenot present. Few things are more disconcerting for a reader than receiving areport which lacks page numbers and which is not in the correct order.

You should also consider the following conventions as you number yourpages. Traditionally, the page numbers for the prefatory pages (i.e., the ab-stract, the table of contents, as well as the list of figures and tables) of mostreports are conventionally located at the bottom center of the page. Uselower case Roman numerals for these pages (i.e., ii, iii, iv, etc.) and do notnumber the title page, even though it counts as page i.

Page numbers for the body of a report are generally located in the upperright corner of the page (or on the upper outside edge of the page if you areprinting on both sides of the page – that is, alternating from top right to topleft corner). Occasionally, page numbers are placed in the lower corners ofdocuments, but we discourage that practice as most readers expect to findthe page numbers in the upper corners and that is usually where they firstlook. Paginate the body of a report in Arabic numbers (i.e., 1, 2, 3, 4, etc.).Also note that the page number on the first page of a report as well as on thefirst page of each chapter in a manual or handbook is sometimes suppressed.

Figure 27 indicates the conventional placement of page numbers in theprefatory and the body sections of a document.

Figure 27: Conventions for Page Numbering


110

Note, however, that just like the convention for indicating a paragraphbreak, the convention of using lower case Roman numerals located at thebottom center for the prefatory pages seems to be changing. In industry,reports and project documents are often numbered using only Arabicnumerals, starting with the title page (which may or may not have a pagenumber on it).

In this case, the change in convention has probably occurred because it is in-trinsically a bit simpler to number pages in that fashion rather than to set upseparate sections with different conventions for the prefatory pages and thebody of the document. In other words, the change here may have a lot to dowith the writers’ abilities to operate their word processing software.

3.3.2.4. Headers and Footers

With the exception of résumés, headers and footers are rarely used in shortdocuments. In longer reports or manuals, however, headers and footers canbe an elegant way to add a professional appearance to your documents. Inaddition, and perhaps more importantly, headers and footers are used tocommunicate important information to the reader.

Chapter or section oriented headers can help readers easily find a particularsection in a manual or a handbook by identifying the chapter or section titleand number. In other cases, headers are used to provide the company nameand/or logo. In the case of a résumé, headers often include the name of theapplicant. Generally, the page number also appears in the header.

Footers, on the other hand, are often used to provide information about thedate the document was prepared and its revision number. In addition, foot-ers are sometimes used to indicate that a report contains confidential or pro-prietary company information.

A final point to consider about headers and footers relates to ensuring thatthey do not crowd the text on the page (this crowding can be a particularproblem if you are using both footers and footnotes). Headers and footersare generally placed in the upper and lower margins about ½ inch from theedges of the paper. Ensure that you leave about ½ inch of empty space be-tween the header and footer and the text on the page. If using footnotes, youshould generally leave ¾ to 1 inch of space between the footer and the note.

3.3.2.5. Tables of Contents

A table of contents is usually only included in a document that exceedsseven or eight pages in length. The table of contents should list at least twolevels of headings down the left-hand margin of the page and the pagenumber down the right-hand margin. The format should clearly indicate thelevel of each heading. Note that you do not include the title page or table ofcontents among the headings listed in the table of contents, but you doinclude the page numbers for the abstract, list of figures, and


111

acknowledgments. If you have more than one appendix, you should providedescriptive headings for each one. Figure 28 provides a sample table ofcontents.

Table of Contents

Abstract ....................................................................................................ii

List of Figures and Tables ........................................................................iv

Introduction and Background ....................................................................1

Kirchhoff’s Laws and Norton’s Network Theorems...................................2

Part 1: Verifying Kirchhoff’s Current and Voltage Laws ..........................5Experimental Procedures...............................................................5Results & Discussion.....................................................................6

Part 2: Determining Norton Equivalent Circuits Directly..........................7Experimental Procedures...............................................................7Results & Discussion.....................................................................8

Part 3: Determining Norton Equivalent Circuits byMeasuring Current vs. Voltage Characteristics..............................9Experimental Procedures.............................................................10Results & Discussion...................................................................12

Conclusions ............................................................................................14

Glossary..................................................................................................16

References...............................................................................................17

Appendix ................................................................................................18

iii

Figure 28: Sample Table of Contents

If you are using the automatic table of contents feature of your word proces-sor, you should find it relatively easy to produce the table of contents. How-ever, you should not simply accept the default style that is provided withmost word processors as this will often result in some of the page numbersin the table of contents being of a different size and style than others (i.e.,some may be 12 point bold while others may be 10 point italic, etc.). Thislooks decidedly odd. We recommend that you set up the table of contents ina relatively consistent and plain format and then bold main headingsmanually

We also suggest that you use dot leaders to connect the title with the pagenumber, especially if the table of contents is lengthy. The use of dot leaders


112

helps ensure that the reader identifies the correct page with the sectionheading, when they are looking up information.

3.3.2.6. Lists of Figures and Tables

Although figures (including graphs) and tables should be listed separately,you can include both lists on the same page if they are both relatively short(as illustrated in Figure 29). Exclude from these lists any figures or tables in-cluded in appendices. Graphics in appendices are generally referred to in thetext by Appendix and page number (i.e., “See Appendix A, p. 18”).

Also note that if you have only one or two figures in a relatively short docu-ment. (i.e., an eight-page report), you can omit the list of figures and tables(but if you have three figures and one table, you would list the table as wellas the figures).

List of Figures

Figure 1. Simulation of Logic Gate with Resistors................................... 3

Figure 2. Bandpass Filter Network.......................................................... 5

Figure 3. Low Pass Filter ........................................................................ 7

Figure 4. High Pass Filter ....................................................................... 8

Figure 5. Low and High Pass Filters with Op-amp Buffer ..................... 10

List of Tables

Table 1. Effect of Load Impedance on Frequency Output ....................... 4

Table 2. Calculated Bandwidth and Insertion Losses ............................. 6

Table 3. Attenuation due to Stray Capacitance in a Circuit .................... 9

iv

Figure 29: Sample List of Figures and Tables


113

To reiterate, we suggest that you use the automatic features of your wordprocessor for producing the list of figures and list of tables because it simpli-fies the task.

3.3.3. Graphical Elements

Entire textbooks have been written about how to use graphics effectively inthe field of engineering. To provide the level of detail you would need in or-der to master the production of graphics is beyond the scope of this text;nevertheless, we would like to draw your attention to a few basic points thatyou should consider when you first start working with graphics.

3.3.3.1. Figures and Tables

Consider the alternatives presented in Figure 30 and Figure 31 for reportingthe change in the temperature of a liquid over a period of time.22

t (time) = 0′, T (temperature) = 25°; t = 3′, T = 27°; t = 6′,T = 29°; t = 9′, T = 31°; t = 12′, T = 32°; t = 15′, T = 32°;

Figure 30: Data Presented in Text Form

time (minutes) temperature (°C)0 253 276 299 3112 3215 32

Figure 31: Example Table with Context on Left

Although the information presented in both formats is identical, most peoplefind the table easier to understand than the text, in part because the table or-ganizes the data visually for the reader. In other words, wherever possible,you should present data in tabular or graphical form rather than in the formof text.

However, simply presenting information in tabular form does not necessar-ily ensure that the information will be easily understood. Consider, for ex-ample, Figure 32.

22 Adapted from Gopen & Swan, “The Science of Scientific Writing,” American Scientist, 78, 1990,

pp. 550-558.


114

temperature (°C) time (minutes)25 027 329 631 932 1232 15

Figure 32: Example Table with Context on Right

Although, again, the same information is presented, most people find the ta-ble in Figure 32 more difficult to understand than the table in Figure 31. Weunderstand new information most readily when we are first provided with afamiliar context in which to place that new information. Because we readfrom left to right, and Figure 31 places the context (time) on the left and thenew information (temperature) on the right, it is slightly easier tounderstand Figure 31 than Figure 32.

By violating our expectation that the context (or independent variable) willprecede the new information (or dependent variable), Figure 32 makes uswork harder in order to understand it. In other words, you need to carefullyconsider the organization of the information that you intend to present infigures and tables. Moreover, because readers generally pay very close atten-tion to figures and tables, you must devote sufficient attention to their layoutand labeling.

By convention, the label is placed below a figure whereas the label is placedabove a table, as in Figure 33.

Figure 33: Placement of Labels for Figures and Tables

However, some companies have recently adopted the practice of placing thelabels above for both figures and tables. Although this change may cause con-


115

fusion for readers who expect the more traditional convention, it makessense from a cognitive perspective. As mentioned earlier, readers process in-formation most easily when provided with a general context before morespecific details. By identifying what the figure is about prior to its presenta-tion, this newer practice may make it easier for readers to understand thesignificance of the figure, particularly if the figure is a complex one.

In addition to considering the organization of your figures and tables, youshould ensure that you adhere to the following guidelines for producing ta-bles and figures:

• All illustrations should be mechanically produced if possible andotherwise drawn in black ink.

• Leave about ½ inch of white space between graphics and text.• Mention figures and tables in the text before you present them.• Never place a figure or table in the middle of a sentence.• Figures and tables should be numbered and given informative titles.• Either capitalize the first letter of all major words in a figure or able

title (don’t capitalize articles, prepositions, and conjunctions unlessthey are the first word in the heading) or capitalize only the first letterof the first word in a heading (i.e., “Figure 6: Stress fractures in tita-nium-aluminum alloys”).

• Indicate the source of borrowed data.• Avoid out-of-focus pictures or close-ups of complex devices. Where

you must present complex diagrams, ensure that they are clearly andconcisely labeled.

• Avoid presenting too many numbers in your graphics (i.e., don’t usea spreadsheet or complex table when you could present the same in-formation with a graph).

• In complex tables, use horizontal and vertical lines to help readersfollow the relationship between the data and the variables.

• Use the horizontal (x) axis of a graph for the independent variableand the vertical (y) axis for the dependent variable. In a table, placethe independent variable on the left and the dependent variable onthe right.

• Axis labels should be simple, but must include all the informationneeded to understand the graph (i.e., label the axes of graphs). Placescale units beside major tick marks only.

• Diagrams should be drawn to scale or, if it is not possible to do so,indicate that to the reader.

• Include the zero baseline on your axes when possible. If necessary,show the data is discontinuous with a break in the axis.

• When using graphs or charts, ensure the axes are heavier than thegrid lines. And ensure that curve lines are heavier than the axes.

• Minimize (or better, eliminate) grid lines and ensure they don’t passthrough bars or columns representing data.

• Where possible, use color to distinguish elements within the graphic,to identify parallel items, or to emphasize specific items (but ensurethat you don’t use too many different colors – a maximum of four orfive is a good rule of thumb).


116

You should be particularly careful to label graphs completely. Unlabelled orincompletely labeled graphs do not help readers because they are forced tore-read the text in order to puzzle out the meaning of the graph. Readers areless likely to view a report with favor if their time is wasted. Figure 34 pro-vides an example of a properly labeled graph.

Figure 34: Example of a Graph

Figure 35 provides an example of a table. In particular, note that the columnsare labeled and the information source is given.

Table 1: Mohs Hardness Scale for Minerals

Hardness Common Name Chemical Formula Sp. Gravity

1 Talc Mg3Si4O10(OH)2 2.7-2.82 Gypsum CaSO4 • 2H2O 2.3-2.43 Calcite CaCO3 2.74 Fluorite CaF2 3.0-3.25 Apatite Ca5(PO4)3(F,Cl,OH) 3.1-3.26 Feldspar† KAlSi3O8 2.5-2.67 Quartz SiO2 2.78 Topaz Al2SiO4(F,OH)2 3.4-3.69 Corundum Al2O3 3.9-4.1

10 Diamond C 3.5

Source: Chesterson, C.W. and K.E. Lowe, The Audubon Society Field Guide to NorthAmerican Rocks and Minerals, 1978, (New York: Alfred A. Knopf).

† Figures are for Orthoclase Feldspar. The hardness of Plagioclase Feldspar (NaAlSi3O8)is the same, but the specific gravity is greater (2.62-2.76).

Figure 35: Example of a Table


117

3.3.3.2. Lists

As well as presenting information in figures and tables, technical reports fre-quently use lists to summarize information. Lists are good way to make adocument more concise simply because they eliminate excess words. Whencreating lists in reports, you should keep the following points in mind:

• Ensure that all items in a list have something in common.• Where possible, lists should be grammatically parallel (i.e., they

should either all start with verbs or all start with nouns).• Use bullets (or another symbol) when the items are of equal impor-

tance; use numbers to indicate priority or order of importance.• Use hanging indents when formatting lists in order to make the bul-

lets or numbers stand out clearly from the text.• If possible, restrict lists to 5 or fewer points. If you have more than

five points, see if you can break the list into sub-lists.

Lists can be punctuated in several ways: by using periods or semi-colons af-ter complete sentences (and a closing period after the final sentence in thelist) and by using commas or no punctuation after sentence fragments (if youuse commas, then place a closing period after the last item in the list).Whichever method you choose to use, ensure that you are consistent. Wealso suggest that you introduce your lists with a complete sentence ratherthan with a fragment as the following example illustrates.

Original Revised

In order to improve our facilitieswe must• repair our existing PCs• purchase 11 more hard drives• increase system security• expand our operating hours

In order to improve our facilitieswe must do the following:• repair our existing PCs• purchase 11 more hard drives• increase system security• expand our operating hours

3.3.3.3. Equations

Technical documents often rely upon the use of equations rather than wordsfor communicating information, and for good reason.23 Mathematics is a lan-guage that is much clearer, more precise and more concise in expressingcertain types of concepts than is English. Rather than writing that “the resis-tance of N series resistors is obtained by adding up the resistances of each re-sistor,” it is much clearer to write “the final resistance is

x yii 1

N

==∑ ,

where yi is the resistance of the ith resistor.” Further, by using this form, it iseasier to further manipulate the equation (for example to describe what hap-pens when another resistor is placed in parallel).

23 We would like to thank Jacques Vaisey (Simon Fraser University, Burnaby, BC) for his

assistance with the section about equations.


118

But used incorrectly, equations can be as confusing to the reader as poorlywritten text. Consequently, we suggest you spend some time learning howto format equations in order to make them as clear as possible. We alsorecommend that you spend some time learning how to use the equationeditor that is packaged with your word processor as it automates many ofthe formatting tasks that word processors are not very good at.

Consider the following points when working with equations:

• Use as concise a notation as possible (for example, xii 1

N

=∑ is easier tounderstand than x1 + x2 + x3 + ··· + xN).

• Display equations on separate lines when the expressions becomeeven slightly complicated.

• Number equations that are cross-referenced elsewhere in the text(there is no need to number equations if they are not cross-referencedor if the reference is obvious). Center the equations and place num-bers in parentheses at the right margin:

x = mg sin(θ). (1)

• Ensure that you deal properly with superscripts and subscripts andspace the elements of the equation appropriately because poorlyspaced equations are difficult to read.

• Write equations so they can be read as sentences as and punctuatethem just as you would any sentence.

• To distinguish mathematical variables from regular text, use an italicfont (both in the equation and when referring to them in text) exceptfor function names such as “sin,” “cos,” “log,” “max,” etc. which areset in the normal font. Use boldface for vectors and matrices to dis-tinguish them from other variables.

• Use Greek letters (e.g., α, β, χ, δ, ε, etc.) when appropriate becausethe extra symbol set makes it easier to recognize the concept whichthe symbol represents (unlike Roman letters – e.g., a, b, c, d, e, etc. –which we generally try to form into words). You may also want touse Greek letters to represent an entire class of symbols in yourdocument so that the reader knows something about what is beingsaid as soon as they see the symbol even if they haven’t seen itbefore.

• Equations are generally referenced in the text using the form “we candetermine the force acting on the ball using (1).” An alternative is touse the expression “Eqn. (1),” but this is less common except at thebeginnings of sentences.

• Where possible, avoid starting a sentence with a mathematical vari-able or an equation number.

3.3.4. Referencing Information Sources

Almost every document that we write is based, in one fashion or another,upon the work of other people. We can acknowledge the contributions ofothers to the document in one of three ways: by using including an acknowl-


119

edgments section in our document, by using footnotes to reference the con-tribution, or by using a formal set of referencing conventions.

3.3.4.1. Acknowledgments

When other individuals contribute broadly to a writing project, either byproviding information, suggestions, or financing, or by helping to edit andrevise the document, we should thank them for their general contribution inthe acknowledgments section of a document. These sorts of acknowledg-ments should be relatively short and should not be overly effusive in nature.Acknowledgments that are excessive are not only embarrassing to theperson mentioned, but those sorts of acknowledgments may also lead somereaders to question how much you actually contributed to the document.Simply name the contributor and their contribution. For example, if youwere writing a report about hydraulic erosion, you might say something like“I would like to thank John Smith for contributing his expertise in the area ofhydraulic erosion to this report.”

In other circumstances, individuals may have only contributed to the docu-ment in a restricted fashion; perhaps they provided a figure or suggested anavenue of investigation. In that case, a footnote acknowledging their specificcontribution would probably be most appropriate.

3.3.4.2. Footnotes

Footnotes are generally used for one of two purposes, either to acknowledgea specific contribution (a concept or a figure, for example) to a document orto expand upon an idea presented in the text of the document. In the case ofa specific contribution, you generally would only use a footnote if the contri-bution was of an unpublished nature (i.e., a verbal suggestion, a photograph,a drawing on the back of a napkin, etc.). If the material was from a publishedsource (and we include internal company documents in the definition ofpublished), then you would use a set of referencing conventions to acknowl-edge the contribution. The one exception to this is when you would onlyneed to include one or two acknowledgments. In that case, it is usually sim-pler to use a footnote to acknowledge the source of the contribution ratherthan preparing a list of references.

The other type of footnote (i.e., expanding upon an idea in the text of thedocument) is becoming increasingly rare, in part because it diverts thereader’s attention from the main discussion. In many cases, if the extra in-formation is sufficiently important that you really want to include it, thenyou should try to incorporate it into the text. This is particularly the casewith a very lengthy footnote: either incorporate it into the text or make it intoan appendix.

When footnoting, you should consider several issues of format.


120

• Set the footnote in a slightly smaller font (i.e., 8 or 9 point font size)than the text in order to clearly distinguish it from the text.

• Use a separator (a horizontal line of about 1½ to 2 inches) to separatethe footnote from the text.

• If you have more than 2 or 3 footnotes use numbers for the footnote;if you have only a few notes you can use symbols such as “*” or “†.”

• Avoid using footnotes if your document has a footer; if you must usea footnote in these circumstances, ensure that you provide adequate(¾ to 1 inch) blank space between the footnote and the footer.

• If possible, try to avoid placing more than one footnote on a page.

In any case, these format issues are relatively easy to deal with if you simplyuse the footnote feature that is available on almost all word processors.

3.3.4.3. Referencing Conventions

Please see Module 1 for information on Referencing Conventions.

¦