Help   |   Contact Us

 

Introduction

This is the introduction. It should provide the reader with an overview of the structure and content of the rest of the document. This document has two themes, one concerning a noun, STRUCTURE, and the other a verb DRAFTING. These two ideas are the essential components of managing complexity, and managing complexity is the essence of technical writing. Structure pertains to the structure of the document, as well as the project documented by the text. Drafting refers to the iterative recursive process of zeroing in on a goal, whether a final document draft or the successful completion of a project. Combining both structure and drafting produces design, the focus of elements on a single purpose. Design is both a noun and a verb; the focused elements are both the parts of the whole and the actions that produce it. If there is one thing I hope to convince students of by the end of a semester, it is that "writing is not salad dressing.'' Instead, writing is design, an integral part of any complex endeavor; it cannot just be sprinkled on as the last touch before serving.

The themes of salad dressing, structure, and drafting will be repeated four times during 21W.783 as the following topics are addressed: Introduction (class 1), Style (class 2), Graphics (class 4), and Oral Presentations (class 5). In these notes, a section is devoted to each of these topics. The remainder of the introduction provides an overview of managing complexity through structure and drafting. But first a word on plagiarism:

Don't.2

I would like to think that saying "just don't'' would be more than enough, but about 1 time out of a 100 I need to be more specific. Do not take other people's words or ideas and promote them as your own. The particularly egregious act is to copy, word for word, from another work, whether another student's paper or a published text. Paraphrasing is similarly odious. If you have the urge to commit either act, cite your reference. Citation is not necessarily full redemption, but it insures that you will not be expelled. (I recommend further reading on various shades of plagiarism from Edward White's "Teaching and Assessing Writing,'' pp x-y. When in doubt, cite. It is much easier to edit out excess citations than to combat charges of plagiarism. Once you are suspected of plagiarism, the entire body of your work is called into question. Even if you are cleared of wrongdoing, your work continues to be regarded with suspicion. Err on the side of honesty. No one has ever been expelled from school or lost a job due to an overabundance of citations.

Managing Complexity

The romantics have it that once upon a time, life was simple and good. A single, though exceptional, person could know all there was to know; Aristotle and the Venerable Bede are purported such intellect. For less powerful intellects, complexity was managed through apprenticeship. Information (lore) was conveyed over a lifetime; practice and tradition reinforced the learning. A craftsperson could know everything about the craft.

Now, two thousand years later, the nature of information has changed and the "know it all'' and apprentice approaches to managing complexity are no longer viable. The shear volume of information makes it impossible for one person to absorb all there is to know. Further, the information changes faster than it can be learned through apprenticeship. These fundamental changes have spawned the genre of technical writing, which makes it possible to access, update, and store large bodies of information.

Two levels of complexity must be managed to produce technical writing: the complex idea itself and the interlocking of words on the page used to express the idea. I hope to demystify the complexity of the ordering of words by examining the structure of text and the processes that go into creating it. Managing the complexity of ideas will remain the business of the writer, though the lessons learned managing the complexity of text are readily transferable to other realms.

Complexity management requires design strategies; some commonly applied to technical writing are described below:

  • Simplification: Like "the force,'' simplification has a light and a dark side. Any of the following list items can be used to properly simplify an idea. For example, diverse empirical information can be "simplified'' by abstraction, through the definition of a law or principle. Or, a first semester physics student may be presented with simplified perfectly stiff, infinitely strong objects as the first step in the iterative development of a model. The improper use of simplification is to "water down,'' to remove relevant detail from a perfectly good idea just to make the idea easy to express.
  • Prioritizing: If the project is large, the most important aspects should be dealt with first.
  • Practice/Iteration: I casually overheard on an NPR program that 10,000 hours (a bit more than one full non-stop year, or five years of normal employment, or one PhD) makes you an expert at anything. My quick estimate (8 humanities courses, one lab course, one thesis at MIT plus half that total for high school writing) suggests that an MIT graduate could easily be less than a quarter of the way toward being such an expert. Even if you have a harder time writing than most, I encourage patience and perseverance.
    At the document level, iteration is important because the drafting process transforms the idea as understood by the author into an idea that can be understood by the reader.
  • Structure: Without structure, a design project is no more than a "blob of blup." Structure implies a hierarchy of elements and connection between all the elements. Further, all the elements must add together to produce more than their mere sum. For technical documents, structure increases the ease of finding and absorbing information.
  • Planning: Louis Pasture says, "Chance favors the prepared mind." I say, "Only prepared minds should write longer documents." Planning is the definition or organization of structure. Setting out to write a longer document without planning is a waste of time. First, you will write yourself into a hole. Then your options are to fill in the hole and start all over again or to dig deeper. Sometimes, you need to dig a few dead end holes before you really get started, but, even so, you need to plan to leave yourself enough time to practice digging.
  • Abstraction: Distilling the essence of experience takes vast quantities of disparate experiences and boils them down into a model of how the universe works. Abstraction is a very effective method of simplification.
  • Collaboration: If one person can do a whole project, the project doesn't qualify as complicated. While complicated projects require the collaboration of several people, complexity and the number of collaborators do not scale. With the addition of people, projects become exponentially complex; adding another collaborator may just slow the project down. (See Frederick Brooks' "The Mythical Man Month for more about throwing manpower at complicated, overdue software projects.) Balance collaboration with efficiency, and don't try to substitute collaboration for structure and planning.

In all endeavors, quality is attention to detail: attention to detail in the structure and at every level within that structure.

Characteristics of technical writing

A good definition of technical writing is elusive. Markel, in Technical Writing suggests that technical writing is any document that is "not fiction," but many scientific theories eventually turn out to be fiction. Let me suggest that technical writing is anything that is not intended to be fictional; such a definition includes a shopping list, a letter to the editor, and a scientific journal article. Technical writing can often be identified by the following characteristics:

  • Jargon and abbreviations:
  • Graphics (tables, graphs, figures):
  • Equations:
  • An emphasis on function over entertainment:
  • The document is not meant to be read cover to cover:
  • The document is useful only to a very narrow audience:
  • The document is highly operational:

My addition to this list: for the most part, technical documents have clear deadlines. The product must ship with the documentation; the conference paper must be submitted in time to be published.

The Structure of Documents

Because text is linear and finite, it has a beginning a middle and an end. This structure is maintained at every level of text: the word, the sentence, the paragraph, the section, and the document as a whole.

Rarely does a complex idea have a linear structure. One difficulty that writers confront is compressing a multi-dimensional thought into a one dimensional document. An analysis of water usage might span France, the USA, and the Middle east, lake and river usage, irrigation and power generation, political implications, infrastructure, and technology: a total of 6 dimensions. All the dimensions are interconnected. Somehow each of the ideas must be made to connect in a string of words.

Many structures are possible. The right organization is the one that best fits the purpose.

The elements of structure are unity, transition, and development. All the parts of the whole must be focused on some one purpose. All the elements must connect to each other. The connections must lead somewhere.

Give every document a title. In the introduction section of longer documents, be sure to introduce the structure and content of the rest of the document.

Two types of well defined documents: the proposal and the report.

Proposal Structure
  • Summary -- a brief summary of the whole
  • Introduction -- defines your problem
  • Background -- shows how your solution is likely to solve the problem.
  • Methods -- outlines your solution
  • End stuff -- details, schedule, costs

Then the document falls off the edge of the world; there is no conclusion. The structure of the proposal is governed by how it is read. Most only read the summary.

sample proposal (Courtesy of James Mahoney and Randy Knaggs. Used with permission.)

The report is very similar to the proposal, but includes the results that follow the methods. With results, a conclusion can be drawn.

Report Structure
  • Abstract -- A summary of the problem, methods, results, and conclusions.
  • Introduction -- defines your problem
  • Background -- shows how your solution is likely to solve the problem.
  • Methods -- outlines your solution
  • Results
  • Conclusion

Writing as an Activity

By recording keystrokes and replaying editing sessions, I have studied how people put words down on paper. My initial hypothesis was that good writers could somehow pour a well formed thought from their brains with the greatest of ease. This hypothesis could not have been farther from the truth. The writers I have studied who manage to write "effortlessly'' write gibberish. I call such writers "egocentric writers,'' to compare their behavior with Piaget's "egocentric speech,'' a stage children go through when they talk incessantly without heeding their listener. While some people undoubtedly have an easier time writing than others, good writers do not effortlessly pour words onto the page.

Instead, good writers go through cycles of writing, reading, thinking, and rewriting. The frequency of the cycles and the focus of the rewriting vary from author to author. ESL students cycle at the word level; each word is typed, checked for spelling/agreement, and corrected before moving on. Some authors type entire paragraphs or pages before reading them over. There is no "correct'' recipe that works best for everyone. If how you write works for you, continue; if not, try to change your writing habits.

Habits the author can control:

  • Attention to detail. Pay less attention in early drafts. Proof read in later drafts.
  • Work on multiple documents simultaneously. When stuck on one, switch to writing the other.
  • Work on different aspects of a document simultaneously. When stuck on the text, fix a figure instead.
  • Got writer's block? Force yourself not to use the delete key.
  • Work at different times of the day.
  • Learn your own bad habits. Has every English teacher and thesis advisor associated red ink with your pronouns? Then be sure to scrutinize your pronoun usage. Can't spell? Learn to recognize the words you butcher regularly.
  • Start writing the middle of your document. The abstract is difficult to write; your method section is liable to be easier. Description is relatively easy too.
  • Leave yourself enough time to write well.
  • Avoid binge writing the evening before the document must be finished.
  • Stop writing for at least three days. You can do so if you've left yourself enough time.
  • If you are a perfectionist, suspend disbelief. Documents are never finished, only due.
  • Decide at the start how perfect a document must be. Recognize this threshold and desist from writing further.

The author's ultimate goal is to cultivate writing habits that make the reader happy. This happy event occurs only when the author recognizes the discrepancy between a draft and what the reader wants. The next chapter on style suggests a framework for authors to think about their writing in order to rework drafts to satisfy the reader.

2: This identical punchline can be found in "The Tourch or the Firehose" and MIT guide for TA's (pg 33, copyright 1981). Did I copy it? Not consciously. But it deserves citation nonetheless.

Next Chapter: Style