1. Hints and Tips for Writing Formal/Technical Documents
INF 5180 Spring 2009
Dietmar Pfahl
1/10

2. Why – What – How? Importance of good writing Types of documents
Formal writing guidelines
2/10

3. Importance of good writing
It helps your readers to:
distinguish between more important and less important material
quickly find specific information
grasp the flow of argument, the assumptions (incl. previous/related work), and the context
Recall: Often you don’t have control over the recipients of your document
3/10

4. Types of Documents
Project Documentation (process and /or product related)
Technical (or Research) Reports
Papers and Articles
Bachelor / Master / Doctoral Theses
Books …
4/10

5. Formal writing guidelines (1)
Executive Summary (similar: Abstract):
Purpose (and type) of document
Target audience
Summary of document content
Main results - methods applied - information used
Document structure
Difficulties encountered (optional)
Context of document
e.g., project to which the document belongs, related documents
Status of document
Not relevant for your
INF5180 Reports
5/10

6. Formal writing guidelines (2)
Style issues:
No colloquial expressions or slang!
Appropriate usage of terminology
Consistent wording (one concept – one expression)
Short sentences
Normally: result-oriented (not process-oriented)
Introduce abbreviations before first usage
Neutral style instead of “we …”, “our …”, etc.
After each headline there should be some text …
6/10

7. Formal writing guidelines (3)
Structural information:
Keywords (not needed for INF5180)
Table of contents (incl. heading numbers and page numbers)
List of tables (not mandatory for INF5180)
List of figures (not mandatory for INF5180)
List of references
List of abbreviations (not mandatory for INF5180)
Glossary (not needed for INF5180)
Index (not needed for INF5180)
Additional literature (not mandatory for INF5180)
7/10

8. Formal writing guidelines (4)
Figures and tables:
Have a caption (incl. brief description and numbering)
Are referenced from within the related text
8/10

9. Formal writing guidelines (5)
References:
All literature included in the list of references must be referenced (at least once)
9/10

10. Formal writing guidelines (6)
References:
There are many formats, but whichever is chosen, it must be used consistently
Examples:
University of Calgary: Reference: Citation & Style Guides
American Statistical Association Style Guide
Software Quality Journal, IEEE, Harvard, etc.
10/10