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

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

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

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

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

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

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

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

Formal writing guidelines (5) References: All literature included in the list of references must be referenced (at least once) 9/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