Technical Communications Toolbox

Technical Writing

Learn more about technical writing conventions and how to evaluate your audience.  Also learn good technical writing practices like structuring paragraphs, writing for clarity conciseness and completeness, using proper tense and voice, avoiding plagiarism, and checking for common writing errors.

Conventions

Every type of writing has its own traits and characteristics that help to identify it. Technical writing is not like writing for an essay or newspaper article.  Technical writing generally has distinct features such as the use of headings to organize information, use of table and figures to present information, and a clear and concise writing style.  Table 1 gives more information on typical technical writing conventions compared to other forms of writing (such as essays).

Table 1 – Typical Technical writing conventions

Criteria Technical Writing Other Writing
Purpose Communicate technical information such as an experimental result or design recommendation.  Writing is clear, concise, and complete. To support an argument or thesis, or to entertain.  May have element of suspense to keep reader reading.
Audience Varies, but can be fellow employees, managers, clients, stakeholders, or public. Varies, but often written for the public.
Writing Style Clear, concise, complete.  Direct language with clear purpose.  Technical terms used (may need to be defined). Building purpose.  Laying groundwork to support argument.  Flowing and entertaining style.
Tone Business – professional – formal.  Generally, avoid personal pronouns. Personal – conversational – informal
Structure Highly structured.   Clear headings and sub-headings with short organized paragraphs designed to orient and move reader through. Some structure, but headings may be more intriguing less clear and often sub-headings not used.
Format/Formatting Varies.  Electronic or printed, visual or non-visual, long or short.  Uses headings as well as tables and figures.  Style guides used to establish formatting rules. Varies.
Other Objective and neutral.  Results and recommendations evidence and data driven.  Precise and quantitative. May be persuasive to support an argument.  May use evidence but often more qualitative.

Audience

The first thing to consider in your technical communication is who will be looking at your work.  The communication is not for your benefit, but for the benefit of the audience. Rather than trying to “show what you know,” it is about providing information to the audience.  In thinking about your audience consider the following questions:

  • Who is my target audience? Are they experts in the field, or new to it? Experts will not need as much theory/background or definition of terms, but those that are new to the field will benefit from that information.  Are they internal to the company, or is this an external document?  If internal then you may not have to explain everything in detail and can be more frank with the recommendations.  External work needs to be more polished and may need to provide more background information.  Communication for the public may need to be written in less “technical” language, but communication to other professionals in your field may need to include the correct “technical” terms.  If you are writing for a class, then the professor should help you determine the audience.
  • What do they already know? There is no need to go into lengthy explanations if you can expect your reader already knows the information (remember it’s not about trying to “show what you know”). However, if the reader does not already have the information, then it should be presented to them.
  • What is the goal or purpose in the communication? It is vital that your communication has a clearly defined goal and that is made apparent in the communication itself. Consider the following questions in establishing your goal:  What are you trying to communicate? What are the readers expecting to do with the document? What is the document meant to accomplish? Why has it been requested?  What do I want them to do as a result of reading this document? How can I plan the content to meet my readers’ needs?  Why does this audience want or need to read this document?  Think about these questions, and make sure your communication clearly coveys the answers to these questions.

Once you think about these questions, you can start to outline a communication that is clear and direct and geared toward the benefit of the audience.

Paragraph Structure

It is vital that the paragraphs themselves are well-structured.  Each paragraph should define or explain a single topic or concept.  One of the most common mistakes in writing is trying to explain too many topics within one paragraph.  The structure of each paragraph should be as follows:

  • Topic statement – you need to say what the paragraph is about at the beginning. (This is not recreational writing. There is no suspense to build by keeping the topic hidden.)
  • Development or explanation sentences with details. – This is the heart of the paragraph and where you put most of your explanation.  But remember, each of these sentences should relate to the topic of the paragraph.
  • Learn more about technical writing conventions and how to evaluate your audience.  Also learn good technical writing practices like structuring paragraphs, writing for clarity conciseness and completeness, using proper tense and voice, avoiding plagiarism, and checking for common writing errors.

Summary or recommendation – It is often useful to conclude with a summary or recommendation so that the reader knows what to do with the information they just learned.  However, not all paragraphs will have a summary so this is optional.

Consider the following example:

Paragraph Example

Your paragraph should also present a consistent flow of ideas.  If the ideas in the development section of the paragraph flow smoothly, then the writing appears cohesive.  Often cohesiveness is achieved by maintaining a constant sentence subject.  For example, if the topic of the paragraph is about the ultimate strength of a material, then the strength is the subject in most of the sentences.  Cohesiveness is also aided by transition statements (however, therefore, because….etc.).  These statements help the reader relate one sentence to the next.   See https://www.smart-words.org/linking-words/transition-words.html for some examples of transition words and phrases.

Active vs. Passive Voice

Most technical writing uses passive voice and passive voice should be the preferred method you use.  However, that does not preclude the use of active voice in the correct applications.  For example, consider the following statement:

Active Voice
I placed the aggregates in to the under-water weighing container and determined the submerged weight of the sample.

Passive Voice
The aggregates were weighed in the under-water weighing container to determine their submerged unit weight.

In the passive voice the importance of the statement is directed toward the experimental sample (aggregates) rather than the person doing the experiment.  In technical writing, generally the most important item is the calculation or experiment, not the person doing it.  Therefore, the use of passive voice generally sounds more professional.  In cases where the person or entity doing something is important then the use of active voice may be appropriate.

Tense

You should use the correct tense – consistently – throughout the report.

Use the present tense when describing the purpose, theory, significance, or applications of a report.  In general, present tense is for facts that are not limited by time. For example:

“As a result of wood’s anisotropic structure, the direction of loading is important.”

“Figure 1 shows the result of the experimental test.”

Use the past tense when describing the procedure and the results of an experiment or design. In general, past tense is used to describe things that happened in the past.  For example:

“The data were reduced by averaging two dial-gage readings.”

“The nylon specimen showed a 20% higher strength with the increased loading rate”

Future tense is rarely used, but may be used to describe perspectives about what will be done in the future.  For example:

“In further research, we will examine the role of stress concentrations on the failure.”

Clarity, Conciseness, and Completeness

Often called the 3C’s of technical writing, clarity, conciseness, and completeness help to ensure that the report is unambiguous, direct, and conveys the needed level of information.  The first draft of a paragraph you make will not be very clear, conciseness, or complete – you need to read your writing and make revisions!    Outlining will often help you focus on the topic for each paragraph and improve the 3C’s.  Further reading and revision will help improve the writing.

Clarity

Clarity ensures your reader understands your communication without any difficulty. This means there are no undefined terms that he or she must look up; there are no extraneous words that hide the real message; and there is a logical flow to the communication. The paragraph is arranged so there is a clear topic sentence. The use of pronouns is limited and they are clearly related to nouns (no assumptions on what a pronoun or “this” refers to). Vague terms (such as “greater” or “less than”) are not used without quantitative comparisons.   Precise technical terms are used.   Explanations are specific and to the point, with no assumptions needed to be made by the reader.

Example: Poor Clarity

Clarity Poor Example

Example: Improved Clarity

Clarity Improved Example

Conciseness

A concise report effectively targets the intended audience in both the amount of information (complete without being overly wordy) and the way in which it is presented.  Conciseness is not a word limit, but rather an idea limit.   You should not provide information that is extraneous to the report, nor should you repeat yourself in your writing. You use as few words as possible to get the message across to the reader. Leave out the adjectives unless they help clarify the message. Keep your sentences simple and to the point.

Example: Poor Conciseness

Concise Poor Example

Example: Improved Conciseness

Concise Improved Example

Completeness

Completeness is ensuring the reader has all the information they need to understand the message, make a decision, and take an action. If you leave out something, then the reader might make an incorrect decision. Your paragraph (and report) should be self-contained and complete. You should consider the audience when deciding how much to define in your report.  This may mean providing the relevant background information if you can expect the audience to not know it.

Example: Poor Completeness

Complete Poor Example

Example: Improved Completeness

Complete Improved Example

Plagiarism

Plagiarism is taken very seriously in all forms of technical communication.  Plagiarism is essentially stealing another person’s academic work.  Instances of plagiarism cast doubt upon the author’s entire body of work.  It may seem easy to copy a sentence or two from a webpage, but such behavior is unethical and can lead to failure of a course, expulsion from the university, or loss of your job…..so don’t do it!

To avoid plagiarism:

  • When in doubt cite – if you are not sure if you need a citation…include it.
  • Avoid copy/paste of sentences – even if you intend to rewrite the sentence later in your own words – don’t just paste something in when writing the report. You may forget to change it later.  Always write it in your own words, or paste with quotation marks.
  • Keep track of your sources –Trying to find out where one piece of information came from a week or month after you wrote it may be near impossible, especially if you are reading several sources. Instead keep track and include your citations as you are writing
  • Use a plagiarism checking tool. The university has access to several tools (such as iThenticate) that you can use to double check your work.
  • Practice paraphrasing. See: https://owl.purdue.edu/owl/research_and_citation/using_research/quoting_paraphrasing_and_summarizing/paraphrasing.html

Common Errors

You will identify most grammatical and editorial errors when you proofread your writing. Grammatical errors make your writing look poor and undermine the worth of your results or recommendation, so you are encouraged to check the document thoroughly before submitting it.

Common Grammatical Errors

  • Use the spelling checker included with the word-processing software. This will catch most mistakes, but not all of them. Common mistakes that are not detected by spelling checkers include: course/coarse, to/too/two, their/there, form/from, for/four, you/your and this/his.
  • Use to abbreviate inch (otherwise it is confused with “in”).
  • Make sure that the subject and verb agree:
    • Wrong: “The loose and compact unit weights for the fine aggregate was 90 psf and 102.5 psf ”
    • Right: “The loose and compact unit weights for the fine aggregate were 90 psf and 102.5 psf respectively.”
    • Wrong: “The data for this experiment is available in Appendix A.”
    • Right: “The data for this experiment are available in Appendix A.” Note that “data” is the plural of “datum.”
  • Use a comma between two independent clauses joined by “and,” “or,” or “but.”
  • Use a semicolon between two independent clauses joined by a conjunctive adverb (“however,” “therefore”).
  • Place a period after a citation when it appears at the end of sentence.
    • Example: The density of concrete is most closely related to the density of the aggregate (Smith 2002).
  • Do not begin sentence with numbers.  If you must, spell out the number.

Good Writing Practices

  • Provide transitions between sentences and consider combining short sentences. Transitions indicate the relationship between two sentences (for example, casual, complementary, or contradictory.) Be sure that the sentences in your writing indicate these relationships clearly.
  • Provide transitions between paragraphs. Because you will change topics between paragraphs, you need a smooth transition sentence to guide the reader.
  • Make sure that all your pronouns mean something.
    • Wrong: “In the future, the accountant responsible for the proofs should initial and date appropriate reports, sign out in the proof log, and revise checklist procedures accordingly. This will clearly indicate who has done the proof and when it was performed.
    • Right: “In the future, the accountant responsible for the proofs should initial and date appropriate reports, sign out in the proof log, and revise checklist procedures accordingly. This new procedure will clearly indicate who has done the proof and when it was performed.
  • Avoid personal pronouns.
  • Eliminate unnecessary words: if you can eliminate a word without changing the meaning of the sentence, delete it.
  • Keep the noun and the verb of a sentence together. Don’t separate with lengthy phrases
  • Keep sentences short and direct. If it could be said in two sentences, then use two.
  • Place the topic of the sentence first, and the resolution at the end. Consider the two examples, each sentence has a different meaning because of the reversed placement of topic and resolution:
    • “Bees disperse pollen” versus “Pollen is dispersed by bees”
  • Avoid jargon (convoluted prose or non-technical language):
    • Example: “Rebar” is jargon for reinforcing bar.
  • Avoid using phrases like “as stated above.”  Rather, point directly to the location (i.e. “As stated in Section 4.3.2……” or “As shown in Figure 4.2”)
  • Don’t write like you are instructing someone when describing methods. Make the method part of the paragraph, or provide a procedure in a table.
  • Avoid using bullets to list methods or results.  Try to write in paragraph form (unless bullets are the best way to convey the information – such as in this current list).

Enter your keyword