General writing
guidelines
- Avoid excessively long
paragraphs. Good guideline = approx. 4-5 print/display lines per
paragraph, depending on ability to split up paragraph logically.
- Format “Normal” paragraphs to
generate 6pt spacing above and below each paragraph (already formatted in
this spec).
- Figures:
°
In a large document, all figures should be captioned,
and the caption centered either above or below the figure.
- When
deciding whether to place captions above or below figures, you must be
consistent throughout the entire document.
°
In a doc with numerous figures, each figure should be
numbered (such as, Figure 2-1, …)
°
Numbered figures should be referenced in some way (such
as, “Figure n illustrates …”) before the figure appears in the
text flow.
°
Figure references should always be “forward”
references; backward references (to a previously-displayed figure) are
ideally only to the most recently displayed figure. Otherwise, it may be
better to repeat the graphic as a new figure.
- Try to avoid use of apostrophe
to form possessive nouns – it is difficult to read for some people. In
other words, instead of “…the resource’s functional interfaces…” write
“...the functional interfaces for the resource…” [Note: “for” may
change dependending on the phrase].
- Conventional
practices:
Instead of … |
Write
this… |
i.e., … |
that is, …
or
in other words, … |
e.g., … |
for example, …
or
such as, … |
…, etc. |
…, and so
on. |
°
If three or more items are to be listed in a sentence,
list them as bullet items.
°
Bulleted lists should be numbered only if they
represent a sequence of actions that must be performed in a specific order.
When numbered, they are considered numbered lists, rather than bulleted
list. See discussion on numbered lists later in this guide
°
When writing a bulleted list, each item in the list
should be:
- Capitalized
the same
- Full
sentences, or discrete phrases
- End in
periods, or not
°
If a bulleted list breaks across a page boundary, I
find it’s good to prevent “orphaned” list items of less than three items. In
other words, ensure that at least three list items appear before and after
the page break. If not, then keep the lines of the bulleted list together on
the next page.
- Remember the commas after
introductory clauses:
°
“When …, …”
°
“In …, …”
°
“Because …, …”
°
Used only for sequential listing of items, where
relative order is significant
°
Each item should represent a single physical step or
concept.