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:
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.
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:
In all endeavors, quality is attention to detail: attention to detail in the structure and at every level within that structure.
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:
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.
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.
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.
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:
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.