The content of technical writing is in two levels: a surface level and a deep level. The surface level comprises the words and sentences you use. The deep level contains the underlying meaning. The following two statements are different in the surface level, but identical in the deep level.
Example
Version 1
Having been in receipt of the query in response to the April 4 correspondence, herewithin find the requisite exposition of aforementioned appraisement of said holdings.
Version 2
We received your letter asking about our April 4 letter with the appraisal of your property. In this letter, I explain how we arrived at the appraisal value.
Writing simply and clearly using plain English doesn’t dumb down the writing. You can change the surface level of your technical writing so you convey the same deep message using shorter sentences and simple vocabulary with no loss of meaning. This article will show you how you can write technical writing in plain English so nontechnical readers understand the entire content you want to convey.
Good business writing is a skill you or your staff can learn.
Learn by writing actual documents.
Receive detailed instructor feedback.
Courses customized to your skill level.
VIEW COURSE
Basic Grammar and Writing Skills for Business
A single course that has both a review of English grammar and training in writing clear, quality business writing.
VIEW COURSE
Basic Grammar for Business
This basic grammar course includes a thorough review of the important business English usage rules with pre- and post-testing to let you see how much basic grammar you are learning.
VIEW COURSE
Business Writing Skills
You will learn all the best practices for writing any business document so it is clear and easy to understand.
Technical Writing Guideline 1:
Understand what the nontechnical reader needs.
The first step in technical writing for nontechnical readers is to decide what these readers want or need. Add detail to your technical writing at the level the reader wants or needs. These are examples of the levels of technical writing the reader may want or need.
No detail, only brief summaries of the technical writing
For this reader, state the content of your technical writing of interest to the reader in summaries, procedures, findings, conclusions, recommendations, general topics, and so on.
A minimal amount of detail
Some readers need a small amount of explanation or rationale in the technical writing to understand the content. Decide the type of detail that is of interest to this reader. Write the detail for each technical topic after the summary statement of the information that would be created in the previous step. Look for the opportunity to stop writing detail. In other words, try to write as little detail as you can that will still satisfy the reader’s wants or needs in the technical report. Avoid presenting a lecture on the subject or including information you feel is very interesting but isn’t necessary for the reader to know.
A moderate level of detail
Use a moderate amount of detail in the technical report for a reader who must be able to make decisions based on the information or speak knowledgeably about the subject to others. For this reader, follow the same guidelines presented for the reader who wants only some detail, but add more to fit this reader’s wants or needs. You will have to evaluate the depth at which you are able to stop. Here also, look for the opportunity to stop writing detail.
A great amount of detail
For the reader who must understand the technical report thoroughly, but does not have the technical background, include nontechnical explanations written as technically as the reader’s background will permit. Write the conclusion, recommendation, or topic and follow with enough detail for the reader to understand the conclusion, recommendation, or topic at a nontechnical but thorough level.
Technical Writing Guideline 2:
Follow These Technical Writing Tips to Write Clearly.
The following tips will help you write clear technical reports in plain English for the nontechnical reader:
- Avoid words with three or more syllables.
- Write short sentences, averaging 10 to 15 words.
- Write the technical report as though you were talking to the reader in a business meeting.
- Use plain English rather than jargon.
- Actively look for detail to leave out of your technical writing because it either will not help the reader understand the subject or will not be understandable because the reader does not have the technical background.
- Substitute clear, plain explanations that approach the technical understanding as much as you can, then stop.
- Avoid presenting a lecture on the subject or including information you feel is very interesting but isn’t necessary for the reader to know.
An example of using plain English in technical writing intended for nontechnical readers follows.
Example
Too General
Problems arose in a number of areas of the device that required intervention by a qualified member of staff so remedial action could be taken.
Too much detail, using complex vocabulary
Monitoring the temperature saw a rise from 80.5 degrees Fahrenheit to 124.5 degrees Fahrenheit causing problems in the equipment temperature since the equipment was not created for temperatures in excess of 105 degrees Fahrenheit, a temperature that creates a molecular breakdown of the components. As the optimum operating temperature is 80 degrees Fahrenheit, the result was an expansion of the component part beyond its maximum operating temperature level of 105 degrees Fahrenheit. This in turn led to a failure of the switch that was rectified by the engineer who assessed that the cooling coefficients needed with a possible ambient temperature above the manufacturer’s recommended levels were more in the range of 80 to 90 degrees Fahrenheit.
Three reduced settings were considered, namely reducing the inflow of current by 10%, 20%, or 25%. These would lead to a reduction in the traffic by 13%, 18%, or 32%.
The optimum setting was 25.32% of the 80,000 maximum number of transactions per hour rate, which was achieved by reducing the number of transactions, relaying the overage to other components and switches. The engineer then had to replace the component and reset all of the relevant switches.
Specific and concise
Because of a sudden increase in transactions, the temperature in the component rose to 124.5 degrees Fahrenheit. The component’s parts overheated, causing the switch to fail. To keep the transactions flowing through the system, an engineer replaced the component, reset the switches, and diverted transactions to other components. That reduced the number of transactions by 25 percent, returning the temperature to the optimum level for this component.
Technical Writing Guideline 3:
Write technical writing in clear, complete sentences.
Present the technical report using clear, complete sentences.
- Don’t leave out articles (a, an, the) or other words to make the statements shorter. That doesn’t make them nontechnical. It makes them difficult to understand.
- Keep sentences at a moderate to short length. Avoid having too many concepts in sentences.
- Use active verbs rather than passive verbs.
- Keep your average sentence to between 10 and 15 words.
- Edit wordy phrases to make them concise.
- Use plain English.
Example
Overly complex and wordy
To understand and interpret an applet, the browser must have a Java virtual machine at its disposal. This is the case, in particular with Netscape Navigator and Internet Explorer, as well as Sun’s HotJava. However, we have already mentioned several times that many Web surfers are attached to older browsers with which they feel comfortable. This being the case, if you use Java you will limit the number of visitors who will be able to wonder at what your applets do. In addition, browsers have a configuration option that allows (for security reasons, for example) the Java virtual machine to be turned off. Cautious people make frequent use of this option.
(111 words)
Concise and easy to read
Only up-to-date browsers can use these applets. Since some Web surfers use older browsers that do not understand Java or have switched off the Java option for security, you may have fewer visitors to your site if you use these applets.
(41 words)
Technical Writing Guideline 4:
Don’t dumb down your technical writing.
Some businesspeople with technical expertise object to “dumbing down” technical writing for nontechnical readers. However, they misunderstand what it means to write technical reports simply.
It is possible to dumb down content, but not the explanation. An explanation using clear, plain English words does not require leaving out content; it just means using words and concepts in the technical writing that a nontechnical reader can understand.
For example, the writer would be dumbing down the content of the technical report if he or she wrote, “The Sun is just like a big campfire in the sky.” That’s dumbing down the content because the Sun’s energy comes from nuclear fusion, not the chemical breakdown of wood that occurs in a campfire. However, the writer could write, “The Sun is a ball of extremely hot gases heated by a continuous nuclear explosion at its core that has gone on for 4.5 billion years.” An astrophysicist might refine that to be even more accurate while keeping the technical simple by using plain English.
Writing about complex, technical subjects in ways that help nontechnical readers understand the concepts requires a knowledgeable writer. The more knowledgeable and intelligent the writer is, the more likely he or she will be able to explain the subject using plain English in a technical report for the nontechnical reader. That person understands the subject well and can create ways of writing the technical report without the jargon.
The less knowledgeable the writer is, the more likely he or she will fall into using jargon and complex phrases in technical writing because the less knowledgeable writer doesn’t understand the concepts well enough to explain them clearly.
When you write your technical report for a nontechnical reader, keep the content you know the reader needs—don’t dumb down technical writing. However, use plain English, shorter sentences, examples, and analogies.
Good business writing is a skill you or your staff can learn.
Learn by writing actual documents.
Receive detailed instructor feedback.
Courses customized to your skill level.
VIEW COURSE
Basic Grammar and Writing Skills for Business
A single course that has both a review of English grammar and training in writing clear, quality business writing.
VIEW COURSE
Basic Grammar for Business
This basic grammar course includes a thorough review of the important business English usage rules with pre- and post-testing to let you see how much basic grammar you are learning.
VIEW COURSE
Business Writing Skills
You will learn all the best practices for writing any business document so it is clear and easy to understand.
Technical Writing Guideline 5:
Use clear, simple, plain English in technical writing.
Complex, difficult language is different from jargon. Do not use complex, difficult language in any of your writing, including technical writing for technical readers.
In the left column are complex words that have simple alternatives. When your technical writing is filled with these types of complex, difficult words, it becomes difficult for some readers to understand. Substitute the plain English alternatives to the right of each word.
| Complex, difficult words | Plain English words |
|---|---|
| accelerated | sped up |
| advise | tell |
| along the lines of | like |
| are of the opinion | believe |
| ascertain | find out, learn |
| assistance | help, converse, talk |
| assumption | belief |
| commence | begin, start |
| consummate | close, bring about |
| deem | think |
| despite the fact that | although, though |
| during the course of | during |
| financial deficit | losing money |
| for the purpose of | for, to |
| for the reason that | because |
| forward | send, mail |
| give consideration to | consider |
| have need for | need |
| indicate | show |
| initiate | begin, start |
| in order to | to |
| in view of the fact that | because, since |
| make use of | use |
| nevertheless | but |
| on the occasion of | when |
| peruse | read, study |
| preceding year | last year |
| predicated | based on |
| prior to | before |
| reside | live |
| subsequent to | after |
| succeed in making | make |
| terminate | end |
| utilize | use |
| we would like to ask that | please |
| with reference to | about |
Example
Technical writing with complex language
The 15ATS series toggle switches, in excess of 200 in aggregate, were subjected to unanticipated extremes of temperatures caused by residing in close proximity to the switching unit. This in turn caused heat-induced diminishment of operating capability as the expansion of metal caused a fault whereby the metal connection was induced to fuse. The requisite heat of the aforementioned switch box would have had to have been in excess of 600 degrees Fahrenheit before such effect is exhibited.
Redrafted in plain English
Over 200 automatic toggle switches fused when the keypad melted as the switch box temperature rose to over 600 degrees Fahrenheit.
Avoid jargon in your technical writing for the nontechnical reader. Use it only when you want the reader to understand or learn the jargon or when the reader already knows it.
Technical Writing Guideline 6:
Include definer words to make the concepts in technical writing clear.
You can ensure that readers will be able to follow your explanations by adding definer words that clearly define the words you use. Below are examples.
Example
| Words without definers | Words with definers |
|---|---|
| the plant | the plant with the excessive levels of toxins |
| the software | the software you described in your email |
| the temperature | the temperature above the OEM settings |
Follow these principles to make your wording clear:
- Write definitions at the point in your technical writing where the reader needs them. Don’t use glossaries. Don’t define words at the beginning and expect the reader to remember them throughout.
- The myth of the “scientific” or “businesslike” language is the same myth as the myth of legal language, accounting language, and medical language. The language must be the same for all: plain English.
Example
Technical Writing with difficult language
From any HTML file on a Web site, you can link to files through URLs that point to other HTML files in the same site or to files residing in other domains on other servers. Specifically, these links are URLs, a unique combination of letters, numbers, and symbols that are not displayed. Instead, link text is designated in the HTML as clickable, so identified through the programmed use of underlining and blue pixilation, which may be avoided through the use of cascading style sheet protocols.
Redrafted in plain English
You can link any page to other pages on the same site or different sites using page addresses. For example, the page address that links to our personnel directory is http://joysonco.com/personnel.html. The text normally doesn’t show the page address itself. Instead, it shows a description of the content, such as “Personnel directory.” The description text is normally blue and underlined so you know that when you click on the text, the page will appear.
Example
Writing with difficult language and jargon
Most refractory coatings to date exhibit a lack of reliability when subject to an unrelenting firing of embedded particulate matter in a stream expelled with exhaust gas under extended durations.
Redrafted in plain English
Particles in the exhaust gas eventually wear away the ceramic’s coating.
Good business writing is a skill you or your staff can learn.
Learn by writing actual documents.
Receive detailed instructor feedback.
Courses customized to your skill level.
VIEW COURSE
Basic Grammar and Writing Skills for Business
A single course that has both a review of English grammar and training in writing clear, quality business writing.
VIEW COURSE
Basic Grammar for Business
This basic grammar course includes a thorough review of the important business English usage rules with pre- and post-testing to let you see how much basic grammar you are learning.
VIEW COURSE
Business Writing Skills
You will learn all the best practices for writing any business document so it is clear and easy to understand.
Technical Writing Guideline 7:
Minimize abbreviations and acronyms in technical writing
Keep acronyms and abbreviations under control in your technical writing.
- Use the abbreviation without explanation if everyone knows it (IBM, USA, Washington DC, BMW, PhD).
- Avoid using an abbreviation if it is commonly understood to have a meaning and you are using it for another. For example, do not use PC for “Planning Council” because most people think of PC as personal computer.
- Use the acronyms or abbreviations your technical group or organization normally uses internally without explanation. However, use the full form or a shortened form when writing technical reports for other audiences.
- Use the shortened word form in your technical writing to avoid the abbreviations the reader may not already understand. Cellular Message Switching and Relay Device becomes Switching Device—not CMSRD. However, if the shortened version won’t communicate clearly, use the full name throughout the technical report.
- Avoid abbreviations you must explain in brackets the first time you use them. If any reader has a less than perfect memory, you will be creating confusion. Use the plain English descriptive terms instead.
Technical Writing Guideline 8:
Write your technical report to help the reader.
When you know the subject well and are writing for a nontechnical reader, it is easy to use a patronizing tone or write to the reader as though he or she were a child. Instead, write clear, simple explanations in your technical writing as you would to an intelligent adult.
Follow these principles to help the reader understand your technical report:
- Format the presentation to make the technical writing easy to read.
- Use visuals, graphs, and tables if they present the information clearly. If visuals require that the reader understand the content before being able to understand the visual, the visuals will be of little worth in the technical writing.
- Use headings to divide the parts of your explanation. Skip blank lines between the parts. White space helps readers navigate the explanations. Present the conclusion, recommendation, or topic succinctly at the beginning of the explanation. Then provide the explanation. You may bold the conclusion, recommendation, or topic and skip a blank line after it so it becomes a heading.
Technical Writing Guideline 9:
Divide technical reports into technical and nontechnical parts
If your technical report will be read by both technical and nontechnical readers, write two parts:
- Write a nontechnical part at the beginning. It may be a cover letter, summary, or executive summary.
- Cover letter. A cover letter for a technical report should be brief and formal. It should contain only an introduction explaining the context of the technical report or study, the list of conclusions, recommendations, or topics, and a cordial conclusion explaining that the technical report follows and providing contact information.
- Summary. A technical report summary should be no longer than one page. It will contain the same information as the cover letter without the letter’s introduction and conclusion. Instead, it will contain brief statements summarizing the introduction and conclusion of the technical report.
- Executive summary. An executive summary is a short version of the technical report written for a nontechnical reader. A 40-page technical report may have an eight- or ten-page executive summary. The sections of the executive summary should be the same as the sections in the technical report. An executive summary should not be an introduction to the technical report or a brief, one-page summary of the technical report.
- Write the technical report after the nontechnical part. The technical report should have its own title with words indicating that it is a technical presentation, such as “Technical Description of the . . .” or “Engineering Specifications for the . . .” or other such title. Longer reports with an executive summary should have separate title pages for the executive summary and technical report and numbering should begin again (from page 1) for the technical report.
Technical Writing Guideline 10:
Embed nontechnical explanations with the technical explanations in technical writing
Consider embedding nontechnical with technical explanations in your technical writing when the nontechnical readers have some technical background or interest.
If the nontechnical readers have some technical background or may be interested in seeing the technical explanation, an alternative organization is to embed the nontechnical summaries with the technical explanations. Use nontechnical headings for the sections of the report. Begin each section with a nontechnical summary at the level the nontechnical readers will understand. Follow with the technical information. Mark the two sections clearly using headings such as “Overview” or “Summary” for the nontechnical portion and “Technical Description” or “Technical Specifications” for the technical portion.
