100 likes | 125 Views
Hints and Tips for Writing Formal/Technical Documents. INF 5180 Spring 2009 Dietmar Pfahl. Why – What – How?. Importance of good writing Types of documents Formal writing guidelines. Importance of good writing. It helps your readers to:
E N D
Hints and Tips for Writing Formal/Technical Documents INF 5180Spring 2009 Dietmar Pfahl
Why – What – How? • Importance of good writing • Types of documents • Formal writing guidelines
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
Types of Documents • Project Documentation (process and /or product related) • Technical (or Research) Reports • Papers and Articles • Bachelor / Master / Doctoral Theses • Books • …
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
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 …
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)
Formal writing guidelines (4) Figures and tables: • Have a caption (incl. brief description and numbering) • Are referenced from within the related text
Formal writing guidelines (5) References: • All literature included in the list of references must be referenced (at least once)
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.