Technical Writing Conventions

1
Technical Writing Conventions

• Rodolfo Celis
• Beaver College

2
Principles of Organization
3
A reminder about your diverse audience

• Readers may differ greatly. However, the
  following 4 are likely commonalities to be kept
  in mind
• They are interrupted while reading.
• They are impatient to find important information.
• They may lack certain areas of technical
  knowledge.
• The documents they read are seen by others too.
• Thus, remember the following number one rule

4

• Write for the reader, not yourself.

5
Some technical writing conventions having to do
with structure

• Manage reader illiquidity by writing different
  parts for different readers.
• Emphasize beginnings and endings.
• Repeat key points. Repeat these points.

6
Different parts for different readers

• Some will focus on summaries, some will go
  straight to the analysis or technical
  information. Others will first go to the
  bibliography to see if you remembered to cite a
  key bit of literature.
• Most will begin with the title, however. Dont
  underestimate the power of titles.

7
Different parts for different readers

• For example, the lead-off summary for a report
  may respond especially to the needs of managers
  without the depth of technical knowledge
  commanded by a specialist.
• On the other hand, the technical sections in the
  body may be directed toward specialists.
• Dont let the technical sections slip up on the
  reader. Advertise that this is a technical
  section or technical section upcoming.

8
Different parts for different readers

• How to keep the document from becoming too
  fragmented?
• Use common threads of organization, them, and
  style to help sections hang together as one piece
  of work.
• Things that are good for this are unifying
  questions, or, preferably, on strong and powerful
  central organizing question. Or a list of
  bulleted points that beg further explanation to
  be provided. Or relate it back to bigger selling
  points in the case of a commercial document.

9
Emphasize beginnings and endings

• Reading technical info is different from reading
  fiction.
• You must accommodate impatient readers by placing
  important information where they want it - at the
  beginning and end of the document.
• These are the places where the reader can
  automatically go to answer the question So what
  does this document mean to me?

10
Repeat key points

• Because most people will read your document
  selectively - not sequentially from beginning to
  end - you have to force a narrative through
  redundancy - which may skirt the boundaries of
  good taste when the document is read straight
  through?
• How to get past this latter problem - viz., there
  is a way to avoid styleless or needless
  repetition (it is done all the time in effective
  cover letter / resume combos)

11
The ABC format

• The default for all technical documents.
• Abstract, Body, Conclusion.
• Note that these are simply generalized parts of a
  document, not specific document headings.

12
Abstract

• The abstract answers four questions
• Purpose Why are you writing?
• Scope What work did you do?
• Results What main point do decision-makers want
  to know?
• Contents What main sections follow?

13
Suggestion

• I strongly suggest interweaving some of the
  principles from proposal writing into this, where
  appropriate.
• In particular, it is useful to have a small
  section in which you assert one basic question or
  one basic selling point - the most powerful point
  that can serve as both an organizational crutch
  and memory aid.

14

• Current research on working memory in cognitive
  psychology suggests that new information is best
  retained if it is constantly related to a
  background matrix - either knowledge or
  assumptions already present, or the background
  matrix you have artificially induced by the
  statement of your organizing principle.

15

• Random structure tips

16
Use lead-ins at the beginnings of sections

• You can do this more often than not.
• Lead-ins give readers a road map for what
  follows. They can be as simple as a list of the
  subsections that follow in a section. Readers
  need such direction finders, in the same way they
  need an overview at the beginning of the whole
  document.

17
Include explicit listings

• Almost any series of three or more points
  requires a list. Bulleted or numbered lists are
  easier to read than long paragraphs of text, as
  long as you keep lists from becoming too long.
  Five to nine items are a maximum.

18
Separate facts from opinions

• Not doing so is sure to annoy the intelligent
  reader the problem is, it is very easy to make
  this mistake.
• You can have a separate opinion section in a
  concluding section like - further research,
  recommendations.

19
Possible conclusion points

• Recommendations
• Further research directions that are now enabled
• Ironic ending that your new data/analysis
  suggests (the twist of the tail)
• Summary
• Re-stating of main point/conclusion
• The single point youd like to leave your readers
  with.

20

• Page design

21
Page design

• The collection of formatting techniques used to
  draw attention to your writing and engage the
  interest of readers. Examples include use of
  white space, headings, lists, and typefaces.

22
White space

• A well-known design rule is to use white space
  liberally. Empty space on the page acts like a
  magnet in drawing the readers eye to the text.
  It can also relieve visual monotony of printed
  words.
• Following are some suggestions for using white
  space effectively.

23
Using white space

• Frame text with 1 to 1 1/2 inch margins. You may
  want to use an even greater margin at the bottom
  of the page.
• Depending on the document and context, experiment
  with double columns. Double columns can relieve
  the strain of long lines of text (imagine the
  newspaper if it were not in double columns).

24
Using white space

• Skip lines between paragraphs in a single-spaced
  text. It is generally suggested, however, that
  you indent paragraphs, however.

25
Using white space

• Use ragged right margins in short documents.
• The uneven edge adds visual variety needed to
  keep the readers attention. Reserve a
  right-justified right margin for some formal
  documents, where a book-like appearance is
  expected.

26
Using white space

• Use slightly more space above headings than below
  them.
• The additional space helps to separate a heading
  and related text from that which came before it.

27
Use headings and subheadings often

• Headings are labels used to introduce new
  sections and subsections. Besides helping
  readers stay on track, they provide visual relief
  from the monotony of text and assist in finding
  specific information later.
• Following are some suggestions for producing an
  effective heading structure.

28
Use headings and subheadings

• Avoid single subheadings for a heading (anything
  divided has at least two parts).
• Maintain parallel grammatical form in headings of
  equal importance.
• Try to have at least one heading on each page of
  text.

29
Use substantive wording

• Readers prefer headings that reflect content.
  Use concrete language rather than abstract nouns,
  even if the headings end up being longer.
• Thus, Surveying the graduates would be
  preferable to methodology. Background on the
  Bentley Dam Failure would be preferable to
  Background.

30
Establish a clear visual ranking of headings

• Usually, the word processor will do this for you
  automatically.
• Check, if possible, with the audience first - you
  tend to see striking visual differentiation of
  headings outside of academia.