1. Technical Writing for Researchers and Graduate Students
Spring 2003
Lincoln Campus
Instructor: Deborah Derrick

2. Unit 2 OUTLINE OF TOPICS: Assuring Quality Content
Writing to Your Audience
Other Writing Guidelines
In the first 4 units of this seminar, we are focusing on CONTENT. Content is the most fundamental writing problem for researchers. Researchers have trouble figuring out what information to include in a report or paper, and how much technical detail to include. Their supervisors—managers and advisers—have trouble understanding what was written. They want the information to be organized, clear and concise so they can read and understand it quickly.
In the first session, we talked about a framework you can use to help organize your notes and structure your document. If there are students here today who did not attend Monday’s class, I have a copy of my presentation on the table.
Today I will talk about other factors that impact or influence content.

3. A quality document … Has the right level of technical detail
Is concise and short
Is clear
Is focused, complete, and logical
I am going to talk about each of these four points in more detail.

4. The right level of detail
A key content problem for researchers is determining the right level of technical detail or information to include in a report.
How can this problem be solved?

5. The right level of detail
To help solve this problem, you need to first establish some CONSTRAINTS for your document.
One of the main constraints to consider is your AUDIENCE.

6. Defining your audience
In scientific writing, you write for one or two specific goals:
To INFORM readers about the problem you are trying to address; and/or
To PERSUADE readers that your solution will help solve the problem
In many documents you do both. For example, in a paper in which you present information about a new algorithm you have developed, you would first inform your readers about the problem you are trying to address. Then you will try to persuade your readers that your solution is effective and will help solve this problem. Success in scientific writing depends on you making a bridge to your audience. Each word and illustration you use depends on your audience, so defining your audience will help you decide on the right level of detail to include.
In scientific writing, unlike journalism, the types of audiences vary tremendously. A scientist or engineer writes to many different audiences. For example, let’s suppose that you used technology from weapons research to design an electronic implant for delivering insulin to diabetics. You might write one document to other engineers who are familiar with the electronics of your design, but not with its application to combatting diabetes. You might then write a second document to medical doctors familiar with diabetes, but not with the electronics of your design. In a third document, your audience might be managers who control the money for your project, but who are unfamiliar with diabetes and electronics. Here you have 3 different audiences and 3 different documents.

7. Defining your audience
WHO will read the document?
WHAT do they know about the subject?
WHY will they read the document?
HOW do they plan to use the document?

8. Suggested methods
Talk with your adviser about the level of detail needed for each part of the document or even for each task.
Your adviser should help clarify the amount and type of supporting documentation or data to include.
Find out constraints on page length.
Look at similar published documents for “models” you can use.

9. Level of detail problem
The level-of-technical detail problem usually occurs in the “SOLUTION” and the “RESULTS” sections of your paper.
Here are some suggestions for dealing with the problem.

10. Level of detail
A GUIDING PRINCIPLE: Go from the general to the specific.
Writers often assume the reader is as familiar with the subject as the writer, or totally remembers the contents of previous papers on the same subject.

11. Level of detail
Don’t jump into the details without explaining the general idea first!
State your main point FIRST, then explain.

12. Rules of thumb
Include only enough detail to meet the minimum needs of your readers.
Exclude minutely detailed supporting data from the body of the document; if needed, append them in a separate section at the end.

13. Improving readability
Divide the report clearly so readers can turn to the information they need.
Include a detailed “Table of Contents.”

14. Readability
Write informative headings and sub-headings that describe what you are actually discussing.
Use headings and subheadings extensively to help readers grasp and process information more quickly.

15. Readability
Try writing a 1-page summary – up front – that maps out the points in your document.
Within a section (e.g., “Solution”), list the main steps first. Then expand on each step.

16. Readability Use familiar analogies to describe new technical concepts.
For example: “This principle is something like XYZ” (some well-known technical rule that all readers know and understand).

17. Readability
Use simple diagrams or schematics to replace long, complex descriptions of procedures and results.
Sometimes a diagram can clarify information more quickly and accurately than a thousand words.

18. Readability
Put comparative or extensive numerical information into tables, not paragraphs.
Use tables to compare qualitative data such as the performance qualities of products, processes, materials, or similar items.

19. Conciseness and brevity
Concise means excluding redundant, irrelevant, and unnecessary information.
Here are some ways to improve conciseness and reduce length.

20. Conciseness and brevity
1. Remove redundant information
Check your outline to make sure you aren’t covering the same topic more than once.
Review the outline to make sure specific information isn’t repeated (unless it is necessary for understanding).
With a good outline, which we will talk about next Monday, it is faster and easier to spot actual or potential redundancies than with a first draft or a completed document. However, there are a few words of caution:

21. Conciseness and brevity
A few words of caution:
The summary, which should stand by itself, will obviously contain the main points that you expand upon later.
A few main ideas may need to be repeated for emphasis.
If you are too strict about not repeating an idea, the reader may miss the point altogether.

22. Conciseness and brevity
2. Remove irrelevant information
Check your outline to see if there is any unnecessary information.
Discuss your outline with your adviser or supervisor to further identify what information is—and isn’t---needed.

23. Conciseness and brevity
3. Reduce document length
Find out how long the document should be.
Have a peer or an editor check for conciseness.
Delete unnecessary details, but stress and interpret the main points of the results and your recommendations.

24. Conciseness and brevity
Break up your writing into short sections.
Do NOT use 50- and 60-word sentences! Divide the sentence into two shorter sentences.
Break up your paragraphs by finding places where a new thought or idea is introduced, and beginning the new paragraph with that thought.

25. Clarity
Clarity means that what you write is unambiguous—it can have only one meaning.
Clarity is difficult to achieve.
BUT-- clarity can be enhanced.

26. Improving clarity
1. Introduce information in a logical, expected sequence.
Problem
Scope
Solution
Results
Conclusion
When a writing task starts, researchers need to stop thinking in terms of introduction, body, end” and start thinking in terms of problem, scope, solution, results, conclusion.” Once this logical organization pattern has been ingrained and accepted, researchers will have a clearer concept of the necessary content at the beginning of the writing task, and an easier time preparing your material. Your readers/advisers will also have a clear pattern in mind when they read what you write.
Remember, when information does not appear in an expected sequence, readers’ attention is diverted to puzzling of such questions as, “Does the information belong here” or even worse, “Does this information really belong at all?”
This organizational principle also applies to each segment of a document, from chapters all the way down to paragraphs. As much as possible, setting up each chapter on a problems-solution-results basis reinforces the expected sequence idea and improves clarity.

27. Improving clarity
2.Present general principles before going into detail.
Do not jump into minute technical details without first describing, even briefly, the concept or principle underlying the research!

28. Improving clarity This advice may be hard to follow because:
The material is very complex and does not lend itself easily to generalizations.
The general principle itself is difficult to simplify or articulate in non-technical terms.
It is often hard to identify what principle, or level of principle, the readers (your adviser) need to understand.
Researchers often fear that generalizations may not represent their work accurately enough.

29. Improving clarity
Here are some ideas researchers can try to apply to solve these problems:
Even if the technical details are complex, there is always at least one principle, concept, or idea underlying a particular direction of research.
Researchers can introduce caveats, or slightly “hedge” their statements.
Despite the difficulty, researchers must provide this basis – this principle or concept. One researcher told us his professor used to claim, “If you can’t explain the principle in terms that intelligent people can understand, you probably don’t really understand it yourself.”
To overcome fears of inaccurate generalizations, researchers can introduce caveats, or slightly “hedge” their statements. But beware of over-hedging.

30. Logic
Are the problems (needs or opportunities) stated in your first section addressed in the Scope and Solution sections?
Does the solution really follow up on the stated scope and goals?
Do the results follow reasonably from the work described in the solution section?
Make sure you’ve included all the 5 sections (or their equivalents) – first. Then, to assure logic, check whether the information in each section responds to and follows from the preceding sections.

31. Logic
Do the recommendations derive from the conclusions and interpretations of the results? Do they close the loop by referring back to the original problem and goals?
Within each section, are your statements and assumptions logically explained? Or are you assuming the reader can fill in the gaps?
Note that managers and other readers point to the omission of conclusions and recommendations as one of the most severe problems in researchers’ reports. Yet these conclusions and recommendations are often the most useful types of information.

32. Logic
Do inconsistencies or contradictions in information or interpretation appear in different sections? Within a section?
Is the document consistent in order, tables, figures, lists and terminology throughout?

33. Completeness Are all the content elements covered?
Are all the problems and needs stated?
Does the scope reflect the main points of the problem?
Does the solution really solve the problem? If not, is it clear what parts are (or are not) addressed?

34. Completeness (Content elements-continued)
Are the results given for each research task?
Are all the conclusions from the results addressed?
Are recommendations for further action included?

35. Other guidelines Define your terms.
If you must use an acronym (abbreviation), define it first.
Example:
“In this project, we propose to extend our expertise in Constraint Processing (CP) …”
“…computing and compacting solutions to a Constraint Satisfaction Problem (CSP)…”

36. Impersonal vs. Personal
Beginning writers and younger graduate students often think the use of the impersonal pronouns makes their work sound professional and objective.
BUT, this often adds to wordiness, awkwardness and imprecision.

37. Impersonal vs. Personal
Example: “It was found that the temperature is a function of current.”
Who found this, you or the authors of the last citation you mentioned?
It is more precise, concise and better English to say: “We found the temperature to be a function of current.”

38. Impersonal vs. Personal
Remember, you are not writing a user’s manual, but reporting on your research (which has presumably consumed a good part of your life).
The best scientific papers do not shy away from using the pronoun “we” as opposed to the impersonal “it.”

39. Impersonal vs. Personal
In Bohr’s classic 1913 paper “On the Constitution of Atoms and Molecules,” he starts his celebrated derivation by saying:
“Let us at first assume that there is no energy radiation.”
instead of the more awkward:
“First, it is assumed that there is no energy radiation.”

40. Impersonal vs. Personal
HOWEVER, the abstract (or project summary) should be written in the impersonal voice. (This is a convention derived from the fact that the abstract used to be written by the publisher of the scientific document to catalog the work.)

41. Use the active voice
In sentences written in the active voice, action is expressed directly; the subject is doing the acting.
Active voice: “John opened the valve.”
Passive voice: “The valve was opened by John.”

42. Active voice
Your writing will be more direct and vigorous if you use the active voice. The passive voice sounds stiff and weak.

43. Active voice
Passive: “Dolphins were taught by researchers in Hawaii to learn new behavior.”
Active: “Researchers in Hawaii taught dolphins to learn new behavior.”

44. Active voice Passive: Active:
“Control of the furnace is provided by a thermostat.”
Active:
“A thermostat controls the furnace.”

45. Active voice Passive: Active:
“The instruction manuals are frequently updated by our technical editors.”
Active:
“Our technical editors frequently update the instruction manuals.”

46. Use the passive voice…
When the doer of the action is unknown or unimportant (or less important than the action itself).
“The first smallpox vaccination was given in 1796.”
“It was found that a virus induces cells to make interferon.”

47. Use plain language Complex:
“Another very important consequence of Einstein’s theory of special relativity that does not follow from classical mechanics is the prediction that even when a body having mass is at rest, and hence has no kinetic energy, there still remains a fixed and constant quantity of energy within this body.”
Like journalists, the scientist and technical writer should strive for simplicity by avoiding fancy words or phrases. Plain language communicates more effectively than complex language. Remember, communication—not literary style—is the mark of good technical writing.

48. Use plain language Simple:
“According to Einstein’s theory of special relativity, even a body at rest contains energy.”

49. Use specific, concrete terms
Do not say something is good, bad, fast, or slow when you can say:
How good
How bad
How fast
How slow
Be quantitative, not qualitative, when possible.

50. Concrete terms Consider: Or: “He ran fast.”
“He ran the 100-yard dash in 10.2 seconds.” (more concrete)
Or:
“The sun is hot.”
“The sun is almost 11,000F at its surface.”

51. Use of tenses
Use the past tense to describe your experimental work and results, which was completed in the past.
“Sensitivity after drug withdrawal began an average of a few days after the last dose and lasted an average of six days.”
“We used a mixing valve to create a liquid-liquid dispersion.”

52. Use of tenses Use the present tense for most other writing, such as:
Hypotheses
Principles
Theories
Facts