4.  Writing a Document.     

Steps

College sophomores in my literature classes often complain that they have no idea what to write about after studying Homer for half a semester.  They ask what I want, implying that "what I want" is both unreasonable and arcane.  I tell them that I want an analysis of the Iliad that identifies significant ideas.  They apparently do not know what those ideas might be nor how to find them, even though they sat through hours of my analysis and have all taken two previous college courses in composition.  The problem is that I did the analysis, not them.  The "theory" specifies that they watch (or listen) to me do the analysis, so that they can then do something comparable.  When I ask them to write an analysis, they cannot do it, because they have had no practice in doing it.  Theory cannot replace practice.

The only way to become a more skilled writer is to practice.  Writing theory is either entertainment or coaching.  Some people are entertained by discussing how to write or how to swim or how to throw a pot.  I am skeptical that  theory will help you know how to swim, throw a pot, or write.  These are performative skills.  You have to actually swim, throw a pot, or write.  After you have begun to perform such skills, you can be coached to improve performance.  

I cannot offer you formulas or theories that will produce effective documents.  I do not think anyone can.  If they could, college writing courses would not be offered.  I can only coach writers about their documents.   

Writing a document involves several steps, including prewriting steps and post-writing or revision steps.  In most cases, the prewriting study of a topic takes more time than writing the document.  Documents that are effectively organized to be reader centered require tinkering or revision that takes longer than the time spent to write a first draft.  Unless you are immensely talented, you cannot produce finished documents by writing a single draft.  The only way I know to produce effective documents is to have an interest in doing so and then spend the necessary time to do things like repeated audience analysis.

Beginning tech writing students frequently ask for two shortcuts:

You cannot organize material until you have it.  When you have material, then you repeatedly ask about the purpose of the document and reader needs.  The answer to the question about facing white space is almost the same: do more prewriting.  My students do not know what to write about Homer because they have not read his works slowly and thoughtfully.  If they would do that, they would have ideas about the works and consequently be able to write an analytic paper.  The process of "getting started" on a technical report is no different.  Once again it involves the same two basic concerns:

If you cannot get started with the writing of a document, it is often because you have not done enough prewriting work.  Technical writers say they spend 45--75% of their time gathering data.  Perhaps creative writers sit down in front of a blank screen and creatively imagine the experiences and emotions of fictional characters.  Because technical writers must explain mechanisms, processes, and theories, they must study these until they know enough about them to answer the questions that readers are likely to have.  There is no magic way to "get started."  If you do not know what to write or how to organize a technical paper, you probably need to study the problem and data more closely.  Knowledge is infectious.  When you learn something  interesting, you often look for someone to tell.  Ideally you would like to know so much about your topic that you cannot wait to start writing to begin organizing the dozen or more ideas you have about it.

After you have some of that brainstorming or outlining on paper, you think about your audience.  What do they need to know in order to assemble, disassemble, or operate the mechanism?  The process of technical writing frequently oscillates between these two foci: studying the problem and keeping the audience in mind.    

Grasping the problem:  When I use controlled data to do case studies, some students are eager to rush off to do the assignment before they adequately understand the details that make up the human part of the problem.  So they do not know exactly what constitutes the solution to the problem.  Some of the elements of the problem are not entirely explicit and are recognized only by reconstructing the details in your own imagination.  Sherlock Holmes and other such detectives claim that their only talent is to pay attention to the details and to follow the inferences that the details imply.  

Template: You decide on the format or range of documents that are necessary.  Complex problems require many different documents that need to be associated: memos, letters, a proposal, progress reports, an abstract, a final report, evaluations.

Audience Analysis: Try to determine:

Methods for Defining an Audience:

Stating the purpose:  In a sense this step integrates the previous three: the problem is stated for the specific reader you have determined by using a specific template or format.  This step produces much of the informative abstract and the introduction component of a formal report.  In a simpler report you may write: "The purpose of this report is to recommend improved safety methods in receiving, handling, storing, dispensing, tracking, and disposing of hazardous chemicals at WT's chemistry lab."  Such a statement of purpose might not survive revision, but you need such a clear statement in the planning stage.  Such a statement implies the likely components of the document.  In our example, we can anticipate sections on: a list of hazardous chemicals; procedures for how they are received; how they are handled; etc.  

Questions:  The basic question is, what data do I need to have to solve the problem?  Your questions may follow the journalist model:

Brainstorming with team members may well identify considerations you had not thought of.  Be sure someone records the ideas.

Search the Web.  Interview the experts; not just on-site.  E-mail people for quick response.  Surveys provide statistical data.

Review the literature:  After stating the problem, many research articles critically discuss relevant experiments  that have the effect of suggesting that the next obvious step in your field is exactly the research you propose or that you are reporting.  This section is very important in creating authority.  

Table of Contents:  Knowing the problem and having thought about the kind of data you need to solve the problem, you devise steps to collect data.  This might be a full-blown research experiment.  (When I ask my son, who is a medical researcher, what he is doing, his stock answer is: "killing rats.")  Most often you assemble relevant data from rather  informal sources.  Nonetheless, you should try to formulate a plan for choosing data instead of casually selecting anecdotal evidence or following chronological evidence ("what happens next is . . .").

Schedule and Budget:  The judgment here concerns the scale of the project.  As you know, this is often driven by resources.  The question is, "how much money do we have?" or "how much money do we ask for?"  

The problem is a variation of the one in which you have to write an abstract for a paper you are scheduled to give at a conference months away, when you have not yet finished the research, much less started to write the paper!  Isn't this why "good" research projects never end?  They inevitably lead to follow-up projects.  

Still, you need to think about the scale of the project, which is almost always determined by the money and answers such questions as these.  

Better to brainstorm such costs before the project begins rather than to get half-way through the project and claim cost overruns that double the budget.  Or is it?

  Write the draft:  Ah, you finally start to write the thing!  

Stock-plan organization:  Should you let Microsoft organize your document?  Microsoft Word, FrontPage, Power Point, and other powerful software comes with dozens of templates.  There are scores of templates and programs that offer to render "a professional" resume for you, if you simply throw in the data.  The usual advice from tech writers is to avoid giving up control of how your document looks by allowing a program to make decisions for you.  Consider:

Revision: Typically this process takes far longer than writing the initial draft.  How many revisions do you do?  Beginning writers often do not pay enough attention to revisions.  We rarely take the time to revise our e-mail.  Some writers are reluctant to give up tinkering with their document.  Document production may follow these steps:

Project Definition
define: audience, purpose, scope, format		 Document Development
research, writing, design, revision
 
      		Review Content
editing, technical review, usability test
Production Edit
copy marking
Typesetting, Coding (e.g., html), Layout
proofreading
Printing, Binding, Uploading to Website & Release

Distribution, Evaluation
Website promotion 

 

  The Final Draft:  You push the "send" button of your e-mail program.  Remember to keep a copy in "sent" mail.  You upload the Web pages.  Of course, images don't load, links don't work, and you are back to revision.  You mail the hard copy.  

This is still not likely to be the end of the life of a complex document in an organization.  So-called "final" drafts are themselves components in larger processes, such as the cycle of reading journal articles, going to conferences, having a bright idea, doing some preliminary snooping, reading a review of the literature, proposing an idea, writing a formal proposal, obtaining funding, doing the research, etc.  More and more, funding agents require or appreciate evaluation of the project.  

If you produce a Web document, links die and someone (the Webmaster) must periodically check the Website to see that everything continues to work and that the content remains up to date.

Back to navigation