2.  Progress Report: Tech Writing Today.     

Technical Writing Basics 

Some years ago I tried to help colleagues at the Indian Institute of Science in Bangalore develop a technical writing curricula.  Things did not go well.  One of the graduate students was kind enough to inform me that I was teaching "secretarial skills" that were embarrassingly simple.  He explained that they wanted theory.  Okay.  Here is technical writing theory in three fundamental points.

1. Audience Analysis

This feature cannot be emphasized too much.  Many of the errors in technical writing can be fixed by clearly identifying the target reader and his concerns.  What is he looking for?  Just as you have job responsibilities, so does your reader.  

• What are his job responsibilities?  
• What is he interested in accomplishing by using your document?
• What level of detail will he be interested in?
• What is his educational or professional background?  
  • Theoretical science
  • Engineering
  • MBA, money, personnel, facilities, resources
  • Technical: community college, military training
  • Staff, secretarial: high school   

It is all too easy to become absorbed in explaining a process or mechanism and to forget the reader.  We all do it.  Consequently, audience analysis needs to be done several times.  You need to identify your audience before you begin writing to help plan what kind of a document will most effectively meet the needs of your audience.  Often, simply presenting the facts is not enough.  Problems are not entirely technical.  Office politics, personality types, various quirks and pet peeves and sensitivities -- all these supposedly trivial and idiosyncratic details must be analyzed, if you want your document to succeed. 

What if you don't know such details?  You do the best you can.  The important thing is to not pretend that these human factors either don't exist or are irrelevant and unnecessary to consider.  What if you have multiple readers?  This is why you use headlines; so that various readers can quickly find the parts of the document that interest them.   

Not so long ago the attitude of many people involved in computer science was: "if you don't know what I am talking about, leave me alone; don't waste my time."  I understood the point: that I am not a member of the discourse community of computer science.  Nonetheless, I am a "reader" or user who is asking for help.   Real world science, technology, and business require clear communication.  That means that documents address real people who need to understand what you want or what you did or what you recommend.

2. Explicit Organization

After suffering through composition classes, where patterns of organization are "internal" or tacit, I think that many of my science and engineering students breathe a sigh of relief when they find that technical writing relies on explicit organization.  For short documents, a bulleted list may be sufficient to achieve clarity.  Documents reaching two pages or more often require enumerated headlines and graphic clues, such as san serif fonts (e.g., Arial) for headlines, bold font, larger fonts, white-space and indentation -- as well as bulleted lists.  I require my students to use the decimal outline system for nearly every document they write.  They are often mildly embarrassed to get it wrong the first couple of times they use it, usually by failing to be consistent or not paying enough attention to white space and layout.  After they get the hang of it, I am sure that it helps them organize their thinking as much as it helps readers understand the steps of a process or the components of an issue.  

Notice in the decimal outline below that each level of division creates a vertical column so that, for example, you almost immediately see that the first point has five divisions.  Employing consistent font changes, using all capital letters, or bold font are optional.  Margins or white space should conform to the pattern illustrated.  Divisions require at least two entries or subheads.  The decimal outline is especially useful for making each step of a process discrete and easily referred to.  

1.  Immediate Problems with the Plum River Conference 
     Center Drawings:

    1.1.  Out of date drawings: the latest set of prints you sent was 
            delivered to Treadwell yesterday (25 Sept. 01).  They are 
            dated 10 Sept. 01.  

    1.2.  Print quality: sepia prints must be readable.  The prints you 
            sent are not readable.

    1.3.  Readability:  
            1.3.1.  The outlining in changing a tenant use from "retail shop"
                        to "restaurant" in the N.E. wing obscures the lettering 
                        identifying the function.
            1.3.2.  Fire corridor revision was not outlined.

    1.4.  Missing: the fire stairwell exiting the theater does not appear.

    1.5.  Match lines: missing.

2.  Drawing specifications:    

     2.1.  Date: send the most current set of prints to both Treadwell  
             and the City Planning Commission (see 4).

     2.2.  Print quality: make photocopies from original tracings.  
             Sepia copies are not acceptable.

     2.3.  Match lines: clearly marked.

     2.4.  Tenant use: clearly marked, not obscured by lettering.

     2.5.  Revisions: 
             2.5.1.  fire corridor outlined;
             2.5.2.  fire stairwell included and outlined;
             2.5.3.  tenant use function clearly marked.

3.  Delivery specifications:

      3.1.  Ordinary business: send drawings by priority mail to 
              arrive the next business day.

      3.2.  Rush delivery: send drawings by courier to arrive the 
              same business day.

      3.3.  COD shipments will not be received.

4.  Schedule for the Plum River Conference 
     Center Project:

     4.1.   Immediate problem: 
              4.1.1  I expect to receive legible and up-to-date drawings 
                        from you by 2 pm this afternoon (26 Sept. 01). 
              4.1.2. As per our phone conversation, pending my approval, 
                        send identical drawings.

    4.2.    Communications: 
              4.2.1.  AVJ will send revisions of drawings to reach  
                         Treadwell.
              4.2.2.  Pending approval from Treadwell, AVJ will send 
                         approved drawings.   

3. Graphics

Engineers, especially, seem more interested in showing you a drawing than in writing.  At New Mexico Tech I quickly discovered that having lunch with my colleagues required lots of napkins.  Inevitably, they would be used to draw some simple graphic to illustrate a theory or process.  Graphics present their own problems.  

• Few writers feel that they are sufficiently skilled in graphic production.  You typically use what you can find or what you can easily produce, rather than analyze what is needed for clear communication.  
• Graphics need to be considered in association with audience analysis.  A complex graphic may work for your peers but not for other audiences, who may require a serial presentation of select parts of the graphic in order to understand it.  
• Simple graphic literacy used to be a standard goal for technical writing instruction.  Document production for Websites has set much higher standards, requiring us to consider document design and using visual material.

More Characteristics of Tech Writing 

Templates:  Everyone knows what a resume should look like.  There are variations, but every reader expects to find standard components: personal information, education, work experience, accomplishments, and references.  Proposals and manuals and most documents written for organizational use are similarly defined.  Medical and insurance documents are different from those generated and used by the legal community of police officers, lawyers, and judges.  The military has its own distinctive organizational goals and culture, which makes it quite different from the university.  Many businesses specify highly objective standards for various documents.    

Collaboration:  Some professors begin to think of plagiarism when they think about collaboration.  Complex documents usually require the collaborative efforts of several people.  Someone in research does the technical part of a proposal.  Personnel may provide resumes of key personnel.  The business office does the budget.  Public relations describes facilities and capabilities.  Collaboration can be frustrating, because no one seems to have all the control he would like.  Paradoxically, collaborative writing requires both a thick skin and sensitivity.  The author of most collaborative writing is, in a sense, the organization.  

Try not to be overly defensive about your writing.  Everyone gets criticism about their writing.  It is not a personal attack.  It is a request for help; an admission that some reader does not sufficiently understand some part of your document.  Instead of defending your brilliance and condemning the reader as too stupid to talk to, the better strategy is to revise the writing.  Repetition is not a bad thing -- both in writing and in graphics.  

Complex projects often begin with brainstorming sessions.  Each team member pursues her individual interest but frequently communicates with other team members.  The "temperature" of camaraderie or collegiality can be chilly, distant and defensive, or warm and inviting.  Collaboration requires you to listen to people with other views and methods.  It also helps not to sneer when others do not know your jargon or methods of operation.  Nurturing positive group dynamics may seem to be a waste of money and time.  I am sure that universities are not the only place where "workers" spend a great deal of their time together complaining about conditions, policies, and most of all, about their supervisors.  On the other hand, I have a young friend who works at Microsoft and is reluctant to go home, because at work he has catered gourmet food, all the new toys he wants, and interesting colleagues who share his interests.  

Document Design:  The content of technical writing may be highly theoretical and esoteric, but the process of technical communication relies on paying attention to typography, spacing, layout, color, repetition, standard forms, and other mundane factors to produce effective documents.  Document design is concerned with both the appearance and production of documents:

• Look professional and attractive.  A carelessly produced resume, with misspelled words and little care for layout, implies that the writer has better things to do than rivet his full attention and care on applying for the job.  If you don't care what your document looks like, how likely is it that your reader will be attentive to details?
• Easy to navigate.  Technical documents are often long and addressed to multiple audiences.  Most readers are only interested in a part of the document.  Long documents that look like a novel, because they do not use an explicit method of division (such as the decimal outline system) will not be read.  When you are compelled to wade through such documents, what do you do?  You mark the document up with a yellow hi-liter, underline or circle other parts to create divisions.  Web sites without effective navigation tools simply hide information and exasperate those looking for it.
• Quickly intelligible.  Is the world speeding up or is it just me?  No one has the time to hunt for information that you didn't take the time to properly organize with headlines, a table of contents, a decimal outline, or even an index.  Many writers seem to be content with "going through the required motions" to document what they did.  If you want the boss to notice, if you want your document to be read, you must organize it so that it visually displays the major points.

Solves Problems:  Technical writing is often "situational."  The audience is reading your document in order to solve a problem.  They don't care how brilliant you are.  They simply want to find the part of your document that poses the question or problem they have and then read your advice about how to solve the problem.  Freshman writers think that "it is all about them."  Technical writers understand that "it is all about the needs of the reader."

Upgrades:  Pencils to typewriters to laptops and the Internet.  Document production today requires writers to have some competency with ever more sophisticated technology.  Boot up your PC.  Does Windows load?  Show me your homepage.  How do I connect the USB Zip drive?  Burn a CD for me.  Does the CD-ROM play DVDs?  Do you have a firewall on your box?  How often do you check e-mail?  Can you use PhotoShop, PageMaker, FrontPage, AutoCad, Excel?  My colleagues in the English department get by using Word for Windows and an e-mail program.  Technical writers need to be half English teachers, half CS types, and perhaps half of something else -- astronomers, microbiologists, or material engineers.

Back to navigation