Every document created for a project serves a different purpose. Control Philosophies, Technical Specifications and reports are all vastly different documents but the presentation of data usually has the same type of data structure. This article looks at technical reporting that is created as part of the design process and information that should be captured.
Some hints on creating a useful document are as follows:
Be consistent with writing styles and content display. Utilize a consistent font and font size throughout the document. Do not use custom fonts. Fonts that are good for readability are Century Gothic, Helvetica or Verdana. Avoid fonts like Comic Sans, Impact and any font that looks like handwriting.
Keep in mind readability. If the document is unstructured or presented haphazardly, the reader may not understand the point the author is trying to make and this undermines the entire purpose of a technical report.
Know the audience. If the purpose of the document is to communicate an update to a management team, the author probably shouldn't discuss items of a highly technical nature.
Technical Document Sections
The various sections below are recommendations but are included to assist in clarity for the reader of the technical document. When writing a technical document, the purpose is to include enough information (beyond the content) so the reader can understand the content and organization without having to reference multiple documents. The list below is not an exhaustive list of potential sections and additional relevant information may be added.
- Title Sheet & Table of Contents - Allows the reader to navigate the document easily. An overwhelming table of contents will defeat the purpose of the TOC. The depth of subheadings should be limited to three.
- Purpose & Scope of the Document - This should describe what the document is to be used for. What are the limits of the document? For example:
This control narrative is being used to describe the addition of a set of transfer pumps to the Piping Designer Waste Handling Facility (PDWHF) located in Internetville. Its purpose it convey information necessary to complete the process design and control documentation for normal and abnormal operation of the PDWHF.
- Abbreviations & Definitions - List of all relevant abbreviations and abbreviations. When writing the content, an abbreviation has to be specified the first time it is used. Subsequent abbreviations do not need further elucidation.
- List of Figures and Tables
- Revision Table - This should include the current revision and all past revisions. As the document evolves, be specific as to what was changed. When making revisions, don’t delete sentences and paragraphs, strike through the text and color code it showing the text was removed. When adding text, color code it in red to show what has changed since the last revision.
- List of Reference Documents - Drawings, P&IDs, PFDs, internal specifications, etc. If a document is referenced in the report, add it to this list. The purpose of this is to allow the reader to do additional research should they be so inclined.
- Appendices
- Headers, Footers & Corporate Branding
