| |
Standards and Guidelines for Technical
Writing
The Robert R. McCormick School
of Engineering and Applied Science
2004
Faculty at the McCormick School of Engineering
and Applied Science expect all student writing to reflect a high level
of professionalism and the standards for excellence that are generally
followed in engineering journals and professional business documents.
The following list of standards summarizes widely accepted views, best
practices, and requirements from leading technical journals, technical
communication textbooks, and feedback from Northwestern’s engineering
and writing faculty. They have been compiled here with the help of funding
from a Walter P. Murphy grant for undergraduate education (2004-2005).
Each standard is followed by guidelines or advice to clarify its meaning.
For examples and further explanation of
the guidelines listed below, consult with Northwestern’s Writing
Place, http://www.writing.northwestern.edu.
Remember: The guidelines provide general advice only; students need to
adapt them to the requirements of a specific department, class, assignment,
or journal.
|
|
| |
Purpose, genre and audience
Standard: Excellent technical
writing has a clear purpose that is well suited to its genre and audience.
Guidelines:
- Choose a genre—e.g. laboratory report, literature
review, abstract, proposal, case study evaluation, electronic memo—that
matches your purpose and will fulfill your intended audience’s
expectations.
- State principle objective of the document early—in
an introduction or purpose section
- Match level of technical discussion and formality
to intended purpose and audience.
- For audience, consider education, professional
experience, reading level, and motivations.
- Use clear and simple diction to make writing accessible
to readers for whom English is not their first language.
- Match content, style, and layout (length) of writing
to communication technology, e.g. print, e-mail, website, slide.
Organization
Standard: Excellent technical writing organizes
information so that main points are easy to find and ideas are easy to
follow.
Guidelines:
- Use appropriate “front matter”—e.g.,
table of contents, abstract, executive summary—to preview a longdocument.
- In the introduction, in addition to stating the document’s
purpose, indicate how the document is organized.
- Use headings and other formatting conventions
to signal major sections, such as Background, Methods, Findings or Results,
Discussion, etc.
- Divide large sections into sub-sections with
second- and third-level headings.
- Use typography that accurately reflects heading
hierarchy* (e.g. 14-point font might be used for major headings
and 12-point for sub-headings, or boldface might be used for major
headings and italics for sub-headings).
- Ensure that all information in a section logically
belongs under that heading; for example, distinguish between findings,
which belong in a Results section of a report, and interpretation
of the findings, which belong in the Discussion section.
- Structure paragraphs to highlight one main idea,
introduced by a clear topic sentence.
- Use transitional words and paragraphs to show
how ideas are related:
- From one idea to the next within a paragraph
- From one paragraph to another within a section
- From one section to another within a long document
- Number all pages, sections, slides, etc.
- Put additional information such as raw data or interview
scripts in appendices; number appendices sequentially and refer to each
in the body of the document.
Return to top
Logic and reasoning
Standard: Excellent technical writing (1) describes
technical information clearly and logically and (2) makes strong, persuasive
arguments.
Guidelines:
- Summarize information succinctly and accurately.
- Synthesize research and key ideas; that is, integrate
ideas from different sources to make a new point or argument.
- Describe complicated ideas by breaking them into
parts and discussing them in a logical order (chronology, cause-effect,
spatial organization, most important to least important, sequence—first,
second, third, etc.)
- Back up all assertions with evidence, reasoning,
and/or authority.
- Cite only credible sources and authorities; carefully
evaluate all sources of information and data.
- Avoid over simplification, omission, or distortion
of ideas and data.
- Consider readers’ cultural backgrounds (ethnicity,
nationality, religion, gender, occupation, age, etc.) when planning
persuasive arguments.
Return to top
Sentence structure and style
Standard: Excellent technical writing is clear,
concise, unambiguous, and direct.
Guidelines:
- Eliminate redundant words and phrases.
- Choose carefully between active and passive
voice.
- Use active voice to avoid wordiness and ambiguity
and to emphasize the agent of an action.
- Use passive voice to emphasize the receiver of
action or to promote coherence (i.e. “flow”).
- Structure sentences for easier reading: put verbs
and familiar information at the beginnings of sentences, lists and new
information at the ends.
- Choose words carefully
- Use technical terms precisely and accurately.
- Avoid loaded language and bias.
- Use plain, direct language that communicates
clearly across cultures and countries.
- Use jargon and acronyms only with audiences who
will be familiar with them. Explain (define) all acronyms.
- For team writing: ensure consistency of style (voice,
point of view, level of formality, etc.)
Return to top
Tables, charts, graphs, and figures
Standard: Excellent technical writing communicates
visually as well as verbally.
Guidelines:
- Use figures, charts, and graphs to help readers visualize
information and therefore better and more quickly understand.
- Use tables to present numeric data in an accessible
and space-efficient format.
- Use photographs, drawings, and maps to provide accurate
visual depictions of objects, processes, and locations.
- Follow best practices in slide design: logical order
and agenda slide, minimal text, large enough font, key idea in headline
or take-away box.
- Follow best practices for graphs and charts:
labels on axes, avoidance of 3D and legends, selective use of detail,
appropriate scale.
- Use the right kind of chart to communicate information—e.g.
pie chart to show parts of a whole, bar graphs or 100% column charts
for comparisons, flow chart to show process, etc.
- Number all figures and tables sequentially.
- Use a specific, accurate title for each figure and
table that ties it closely to your text.
Return to top
Equations and numbers
Standard: Excellent technical writing uses equations
and numbers to communicate ideas.
Guidelines:
- Use widely known and accepted formulas for calculations.
- Include all major calculations, if not in the body
of the report, then in the appendix.
- Use equation editors to present mathematical formulas
in the text.
- Provide units with a unit convention (i.e. SI units,
Imperial units) for each quantity. NB: The international system of units
(SI units) is most commonly used in engineering journals.
- Use scientific notations when expressing very large
or small values (e.g. instead of 1,000,000, use 1x106)
- Account for unavoidable uncertainty in measurement
through the use of significant figures.
- Consider physical meanings of quantities when reporting
(e.g. a human being cannot weigh 1000 kg).
Return to top
Grammar and punctuation
Standard: Excellent technical communication adheres
to conventional rules of grammar and punctuation.
Guidelines:
- Write grammatically correct, complete sentences.
- Avoid using commas to connect complete sentences.
- Make lists grammatically and logically parallel.
- Make sure that all pronouns refer to clear antecedents.
- Follow conventional spelling and punctuation rules;
proofread for correctness.
- Avoid overly formal language or grammatical constructions.
Return to top
Bibliography and references
Standard: Excellent technical communication cites
all sources clearly and completely.
Guidelines:
- Provide complete, accurate bibliographic information
for print sources, online sources, personal interviews, site visits,
etc.
- Use the bibliographic style expected by your audience
and discipline. For example, many engineering journals require formatting
of references be done using AMA (American Medical Association) style,
but others use the styles recommended by the ASCE (American Society
of Civil Engineers), the ACS (American Chemical Society), etc.
- Include citation indicators within the text (i.e.
numbers or author name and year), and link them to the references page
(use a consistent format; order the references either with numbers or
first authors’ last names).
Return to top
|
|