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.