|
|
Basic Technical Writing Tips
KISS - Keep It Simple and Short
 | Remove redundant words and phrases from
sentences. |
| Do not repeat yourself. |
| Avoid colorful language and adjectives.
|
Lead the Reader
| Direct the reader through your text using
subtle or not-so subtle guides. |
| Paragraphs should "flow" together in text.
|
| A paragraph should have an opening sentence
representative of its general contents and often have a closing sentence to
summarize the paragraph discussion. |
| Organize your presentation into sections
such as introduction, motivation, background, topic related sections, and
conclusion. |
| Try to avoid directly referring to the
reader such as "Let us examine ..." or "As you will see..."
|
Be Intelligent but not Too Smart
| Use more technical and descriptive words
whenever appropriate, but do not use a thesaurus just to look "smarter".
|
Use Bold and Italics Productively
| Bold and italics are intended to draw a
readers attention, so do not abuse them. |
| Use bold/italics for definitions or
important words in text. Example: "An object consists of attributes
and methods." |
| Underline is rarely used. |
General Tips and Common
Mistakes
| Unnecessary Capitalization
- Do not capitalize terms in sentence unless they are proper names.
|
| "Because ..."
- Do not start a sentence with because. Re-arrange your sentence so because
is not needed or substitute "Since ..." or "Due to ...".
|
| Avoid Abbreviations
- Do not use abbreviations such as "let's" (let us) and "that's" (that is).
|
| Avoid Self-References
- If possible, do not use "I" in the text. Change the sentence to avoid a
self-reference or substitute "we" if appropriate. |
| Dangling "This"
- Do not abuse "this" to substitute for a topic in discussion. "For example,
this is a bad situation because the sentence is ambiguous." Replace "this"
with the item being described such as "Using the word 'this' inappropriately
results in a bad situation because the sentence may be ambiguous."
|
| Define Before Use
- For terms and abbreviations, please define before use (DBU). Otherwise,
the reader may not understand the concept or abbreviation if you do not DBU.
|
| New Paragraphs
- As a general rule, split larger paragraphs into two or more paragraphs if
the topics describe are sufficiently distinct. |
| "Further" Instead of "Also"
- Replace "Further" with "Also" to start a sentence.
|
| Be Consistent with Terms
- If you define a term, abbreviation, or proper name, be consistent in its
spelling, use, and capitalization throughout the text. |
| Dangling Headers
- Do not have text headers end a page followed by no text. Similarly, try to
avoid lines of text with only one or two words at the end of a paragraph.
|
| Title Capitalization Rule
- Headings should be capitalized (i.e., nouns, verbs, and all other words
except articles, prepositions, and conjunctions should be set with an
initial capital) and should, with the exception of the title, be aligned to
the left. Words joined by a hyphen are subject to a special rule. If the
first word can stand alone, the second word should be capitalized. Here are
some examples of headings: "Criteria to Disprove Context-Freeness of Collage
Languages", "On Correcting the Intrusion of Tracing Non-deterministic
Programs by Software", "A User-Friendly and Extendable Data Distribution
System", "Multi-flip Networks: Parallelizing GenSAT".
|
| 'An' versus 'A':
 | Mnemonics such as XML requires the
article 'an'. Example: an XML document |
| Words beginning with 'u' require the
article 'a': Example: a unique or a unified approach |
|
| 'That' versus 'Which'
- 'That' should be preferentially used instead of 'which'. |
Writing Resources
| William Strunk, Elements of
Style, New York, 1918.
|
| Justin Zobel, "Writing for Computer Science - The Art of Effective
Communication", Springer, 1997. |
Research and Writing Resources
Paper Style Templates
|
