Chapter 1: Introduction to Technical and Report Writing

The Meaning of “Technical”

Technical communication—or technical writing, as the course is often called—is not writing about a specific technical topic such as computers, but about any technical topic. The term “technical” refers to knowledge that is not widespread, that is more the territory of experts and specialists. Whatever your major is, you are developing an expertise—you are becoming a specialist in a particular technical area. And whenever you try to write or say anything about your field, you are engaged in technical communication.

Academic Writing Versus Technical Writing    

The definite purpose, strict format and use of appropriate language in technical writing define the differences between technical writing and academic writing.  The academic writer’s purpose may be to write an assignment, a story, a letter, etc.. These works may or may not have a reader. However, technical writing always has a definite purpose and will always have a reader.  Regardless of the number of the intended readers of a document who may or may not read the document, the document will be read by the primary reader.

Workplace Writing

However, the focus for technical-writing courses is not necessarily a career as a technical writer but an introduction to the kinds of writing skills you need in practically any technically oriented professional job. No matter what sort of professional work you do, you’re likely to do lots of writing—and much of it technical in nature. The more you know about some basic technical-writing skills, which are covered in this guide and in technical-writing courses, the better job of writing you’re likely to do. And that will be good for the projects you work on, for the organizations you work in, and—most of all—good for you and your
career.

Really Technical Writing

Keep relaxing, but you should know that professional technical writers do in fact write about very technical stuff—information that they cannot begin to master unless they go back for a Ph.D. But wait a minute! The technical documents have to ship with the product in less than nine months! How do they manage? Professional technical writers rely on these strategies to ensure the technical accuracy of their work:

• Study of books, articles, reports, websites related to the product
• Product specifications: what the product is supposed to do, how it is designed
• Interviews with subject matter experts: the product specialists, developers, engineers
• Product meetings during the development cycle
• Live demonstrations of the product
• Familiarization with similar, competing products
• Experimenting with working models of the product
• Most importantly, subject matter experts’ review of technical writers’ work for technical accuracy and completeness

Of course, experienced technical writers will tell you that product development moves so fast that specifications are not always possible and that working models of the product are rarely available. That’s why the subject matter experts’ review is often the most important.

Considerations of Technical Documents

There are key components of what makes a document strong. Therefore, writers keep these items in mind while constructing technical documents.

The Importance of Audience

Another key part of the definition of technical communication is the receiver of the information—the audience. Technical communication is the delivery of technical information to readers (or listeners or viewers) in a manner that is adapted to their needs, level of understanding, and background. In fact, this audience element is so important that it is one of the cornerstones of this course: you are challenged to write about highly technical subjects but in a way that a beginner—a nonspecialist—could understand. This ability to “translate” technical information to non-specialists is a key skill to any technical communicator. In a world of rapid technological development, people are constantly falling behind and becoming technological illiterates. Technology companies are constantly struggling to find effective ways to help customers or potential customers understand the advantages or the operation of their new products.

Not only is the the level at which you write important but so are the language choices you make as you do so. Please review the information on the following link for tips: Use Language that is Sensitive to Your Audience^[2]

So relax! You don’t have to write about computers or rocket science—write about the area of technical specialization you know or are learning about. Also, plan to write about it in such a way that even Grandad can understand!

Formatting and Language

Formatting and appropriate language are the basic design elements of all technical documents.  A format that shows a hierarchical structure and a coordinate structure of information leads the reader thorough text.

Readers should be able to identify a writer’s organizational pattern very quickly when reading a technical document. This sometimes refers to a document being “reader friendly.”  In addition, using appropriate language is significant in providing the reader with a thorough understanding of the purpose of the document, how the document relates to the reader’s needs, and what action is expected of the reader.^[3]

A document may also have one reader (the primary reader) or several readers (the secondary readers). A primary reader is the person who ordered the report to be written or the person for whom a report is intended. These readers will usually read the entire report. Secondary readers are those readers who will read only the sections of the report that relate to them, their jobs, their departments, responsibilities, etc. For example, if a report was sent that detailed funding for different departments, a piping superintendent may only want to read the section that relates to piping. This is where format, the use of headings, is significant in allowing the reader easy access to information. When the piping superintendent can scan through the document and clearly find the heading that identifies his department saves time.

Cultural Communication

Technical writers need to be aware of the differences between the behavior and the norms, beliefs and values of specific cultural. According to Edward T. Hall and Mildred Reed Hall, In Understanding Cultural Differences, each culture operates according to its own rules (1990, pp. 3-4).  Hall and Hall add that problems occur when members of one culture apply the rules to another culture (1990, pp. 3-4). To communicate effectively with other cultures, the technical writer needs to not only be aware of rules governing behaviors that can be observed but also of the not-so-obvious rules that govern the norms, beliefs, and values of the people of a culture. The invisible rules of a culture dramatically impact the acceptance of ideas, plans, and strategies.  The Cultural Iceberg illustrates patterns of world communication, showing indicators of Institutional Culture (the obvious behavior of a culture), which can be clearly seen as the tip of the iceberg, and People Culture (the norms, beliefs and values of a culture), which cannot be seen and which are the barriers to successful communication.

Figure 2 The Cultural Iceberg

Ethics ^[4]

Technical writers have a responsibility to their readers and to their employers to follow ethics when writing reports. 

Technical writers must use words that demonstrate valid appeals to reason, avoiding emotional words and phrases that appeal to basic emotion instead of justifiable reasoning. In addition, technical writers must use valid references to support ideas and strategies, avoiding referencing non experts to sway readers’ support. Also, technical writers must use accurate numbers to report data, avoiding charts and tables that skew data. Using any type of fallacies in technical writing is unethical and could result in dire consequences.

Not only do technical writers have a responsibility to report accurate information, but they also have a responsibility to credit accurate sources of information. At no time is it acceptable to rearrange information in order to attempt to indicate that the writer is the source of someone else’s idea or to indicate that the writer read a report that included information he/she cited, when the primary source of the information was cited in another report.  All sources must be referenced accurately in the text and cited on a reference page.

Daniel G. Riordan (2005), in Technical Report Writing Today, cites Dombrowski to define three threads of ethics:

One major thread is that the communicator must be a good person who cares for the audience. Communicators must tell the truth as convincingly as possible, because truth will lead to the good of the audience. Another thread is that the communicator must do what is right, regardless of possible outcomes. A third thread is that communicators must act for the greatest good for the greatest number of people (p. 16).

In addition, Riordan (2005) references the “code of ethics of the Society for Technical Writers, and cites five of the code’s tenants:

My commitment to professional excellence and ethical behaviors means that I will…

• Use language and visuals with precision.
• Prefer simple direct expression of ideas.
• Satisfy the audience’s need for information, not my own need for self-expression.
• Hold myself responsible for how well my audience understands my message.
• Report the work of colleagues, knowing that a communication problem may have more than one solution (Riordan, 2005, pp. 15-16).

Visuals & Readability

To make a document more reader friendly, many technical writers rely on visuals to achieve this goal. ^[5] For example, labels, callouts and captions are identifying text for graphics. Labels and callouts identify specific elements or features on a graphic; whereas captions are short phrases or sentences that describe the graphic. Notes, or footnotes, explain, or give credit.

Labels and Callouts

To identify specific elements or features, labels and captions are placed directly on the graphic or near it. “Although the terms are used interchangeably, labels are text identifiers that are self-explanatory in an image, while callouts are labels that require further information outside the image to explain what they are identifying” (Gurak 304). They supplement the visual information. But use them selectively; use them only if readers need them (Rude 116).

The advantage of labels is that the reader gains a basic understanding of elements in the graphic without referring to supplementary explanations. But, too many labels obscure the image. In this case, callouts are the better option. Use numbers or letters to identify each element and the supplementary explanations.

Guidelines for Creating Labels and Callouts

• Determine the number of items to identify in the image (Gurak 308).
• Estimate how much explanation each item requires to determine if labels or callouts are more appropriate (Gurak 308).
• When writing labels and callouts,
  • create a consistent visual style (Gurak 308)
  • use the same terms on the label or callout as in the text (Rude 116)
  • in general, all parts mentioned in the text should have a label or callout, and all parts with a label or callout should be mentioned in the text. (Rude 116)

• Layout the labels or callouts next to the elements in the graphic they identify, using a line to connect the two, if necessary.
  • Use a standard font and size for readability (Rude 116)
  • Align the labels and callouts for a neater appearance (Rude 116)

• If callouts are used, place the explanatory text in a key next to the graphic.

Labels

Labels can take different forms (Gurak 304 – 306):

• They may be placed directly on the graphic (whereby they become part of the graphic).
• They may be placed around the graphic and use lines to point to the relevant element in the graphic.
• Online, labels can be links or hotspots whereby more information about the element is displayed on mouse rollover.

This is an example of labels placed directly on the graphic.

Figure 3 Map of the West Side Central Park, NYC between 102nd and 110th Streets.

Here, the labels are placed around the graphic.

Figure 4 Parts of a flower.

In this sample, when the mouse is rolled over the ‘Firebox’ label, the text will read:
“Literally a box containing the fire. It is surrounded by water on the top and all sides. The bottom is a grate with an ash pan below that.” Additional information is displayed.

Figure 5 Labels as hotspots.

Callouts

Callouts are best used when many parts of the image need to be labeled and each part requires a longer explanation. In fact, the label sequence may be in alphabetical or numerical (as in Figure 6) order. Ensure that the explanation is near the graphic.

Figure 6. How to understand and use the Nutrition Facts Label.

Coded callouts are in numerical sequence; the explanation for each number appears below the graphic. The example above
shows part of the explanation of Number 1 explanation only.

Captions

Captions, table, and graphics titles must clearly identify information to the reader. Interpretive captions usually require one or more sentences. Captions should be informational, without becoming too lengthy. Captions that are merely a title for a graphic are not very helpful (Franklin 96).

Writing Style for Captions

• Captions for graphics include the title and any explanatory material, immediately under the graphic.
• Words such as Figure, Illustration, and Table should be in bold type.
• The caption should be italicized.
• Treat tables and figures the same.

Good captions are what guide readers not only to see, but also to understand. Captions label graphics with titles and explain to readers what they are seeing, and how to interpret the information captured in the visual. The Franklin Covey Style Guide for Business and Technical Communication provides an excellent source for writing captions (Franklin 39 – 41).

Five Specific Style Rules

• Use interpretive captions whenever possible. Interpretive captions provide both a title and explanatory information, usually expressed in a complete sentence, to help readers understand the central point(s) that the writer wants to convey. A graphic and its caption should be clear and understandable without requiring readers to search for clarifying information in the text:

• • Figure 4. Cabin-Temperature Control System.Constant cabin temperature control is maintained by the system’s modulated cabin sensor.
  • This interpretive caption gives the title and then tells the reader the principle message – that the check valve provides near-zero risk. And, it states how the check valve provides near-zero risk (Franklin 39).

• • Figure 23. Check Valve. The risk of bad air entering the changer is near zero because the check valve permits air flow in one direction only.
  • This interpretive caption gives the title of the figure and emphasizes that the cabin has a constant temperature – a benefit provided by the feature described in the figure. The caption states clearly what the writer wants the reader to learn from the drawing (Franklin 39).

• Avoid using short, often ambiguous, titles to replace interpretive captions. In the past, styles for technical and scientific documents used only short, simple title captions for visuals. These were often superfluous, providing no real information other than the obvious to the reader, i.e. – A Horse. Titles that are so short and cryptic that they sound telegraphic are not useful. Such captions are only useful when the graphics are self-explanatory, and require no interpretation (Franklin 40).

• Number figures and tables sequentially throughout the document, and place the number before the caption. If an important figure or table is presented twice, treat it as two separate visuals and number each. Figure and table numbers should be whole numbers (Franklin 40).

• Use periods following interpretive captions but no punctuation following short captions that are not sentences. Interpretive captions are usually complete sentences and should therefore end with a period. Short captions, like titles and headings, are not usually complete sentences, so they require no punctuation (Franklin 41).
  • • Captions may appear below or above a visual, but consistency throughout a document is critical. Arguments support both options; choose one, warrant your choice, and be consistent.

• Put the caption above the visual for better visibility when captions are used with slides and other project visual aids. Captions placed at the bottom may be blocked by the heads of those seated in front (Franklin 99).

Notes

Notes or footnotes are categorized as either explanatory or source notes. Explanatory footnotes are identified by a superscript number or letter. The order in which notes appear is important; explanatory footnotes are placed above source notes. And both are placed above the caption, if the caption is placed at the bottom of the illustration.

Figure 7. Placement of footnote, source note and caption.

Source: Rude, p. 115, modified.

The Writing Process ^[6]

Writing, especially when compiling a larger document,  is not something you sit down, complete in one session, and quickly submit. This is especially true when writing for the workplace where accuracy and clarity are necessary. In fact, writing should be seen as a process that is recursive where the writer moves in and out of various stages of writing and often times revisits some of the stages. The writing process might consist of the following:

Prewriting

This is the planning done before writing a document. It may be defining the purpose of the task, analyzing the primary and secondary readers, sketching the document and what will go in each section, or gathering research.

Drafting

This is writing and compiling a first draft of the document. Sometimes, the writer worries more about getting ideas down more than guaranteeing every punctuation or grammar choice is correct.

Revising

When a writer revises, a writer revisits the draft and makes substantial changes to it. This is more than editing. It is adding, deleting, and moving entire sections of the document around to prepare it as a final, comprehensive document. In fact, it is here that many writers ask others for feedback before revising to ensure that another, unbiased set of eyes have looked over the document and easily understand it.

Editing

This is the final part of the process. It is reading through the document several times while looking for clarity, consistency, and accuracy. In fact, consider reading your document aloud and listening to it as you do so instead of reading and “seeing” it. Most individuals communicate mostly through talking and listening. Therefore, when you read aloud, you can hear if something in your document doesn’t sound right and then correct it. You should be able to read it in a way that it is understandable and sounds conversational.

For additional information on the writing process, visit The Writing Center website for the University of Texas: University of Texas Writing Center & The Writing Process.

Using a process in the workplace and in our class will strengthen your documents significantly. In fact, remember that your documents reflect on who you are as student, technical writer, employee, and even researcher.