Elements of Technical Documents
All technical documents are structured in a similar way. They consist of the same elements that help technical writers organize their documents in a clear manner. In this post, I’ve prepared a list of elements that every technical document should contain. As a result, beginners can treat this article as a checklist during developing a tech document.
Front Matter
Front Matter is the most important part of the technical document. It introduces readers into the title of the document, its author(s), the topic(s) described, the issue(s) solved, the method(s) used, and the overall purpose of the document.
Front Matter of any technical document must include the following elements:
- Title page. It should include the title, the author and the date. Title should be both clear and detailed enough, so that readers could easily grasp the idea of what is covered. For example, the title “Solar Absorption by Clouds” fails to deliver the idea of what’s the document is going to be about, how these two categories are interconnected, what is the problem to be solved. So the improved version of this title could be “Direct Observation of Excess Solar Absorption by Clouds”.
- Abstract is a summarizing statement. It should neither be too short, nor too long. About 70–150 words is usually enough. Abstract should contain general information about the topic or issue, methods used, main results, and conclusions of your document. Its content should be clear and straightforward as long as it succinctly communicates the purpose of the following document. So, an abstract can save readers’ time.
- Table of contents is a list of the subject headings and subheadings of the document.
It is usually provided in long documents such as reports, proposals, and other administrative and research documents. Your table of contents should be properly done, so that readers can easily navigate through the document. - List of figures. Numerous research suggest that nowadays people prefer visual content to a text because screenshots, charts, pictures allow readers to quickly get the idea. Visual content is important in technical documentation. Create a list of figures in order to organize the visuals and make them easier to navigate. Make sure to provide them with a description as follows:
Figure 1. A Standard Nichrome Wire Cutter………………………………3
Figure 2. Melting Temperature of Thermoplastics Compared…………….5
( — J. M. Dent, “Strain Cycling of Hot Nichrome Wire”)
- List of tables contains all tables of your document. Make sure not to mix tables and figures in the same list. List of tables is usually organised as a list of figures as described and illustrated above.
- List of terms. Every document contains terminology, acronyms and abbreviations specific to the particular field of knowledge or topic described. Some of these words may confuse even the most knowledgeable readers. That’s why a list of terms is essential in any technical document.
- Acknowledgments. This part of your document should include names of your colleagues, other fellow technical writers and programmers who assisted the development of the document.
Body
Body of the document contains materials with steps to take and/or methods to use in order to resolve the issue presented in the abstract.
- Introduction presents the main goal and what to expect further in document. Introduction shouldn’t be confused with abstract. Introduction contains the subject of your document, the issue resolved, the purpose, its scope and background information.
- Background information should be relevant. Usually, this part includes the history of the problem, a summary of previous research and reasons why you decided to write this document.
- Theory. If the document is comparatively long, you should develop a separate section named “theory” that describes all the formulae and techniques used.
- Design criteria. This section includes proposals, feasibility reports, recommendation reports with the possible design of a product.
- Materials and apparatus. If your document explains, for example, some sort of experiment, you should describe software and hardware used.
- Procedure. Describe all methods that you used for gathering data.
- Workplan. This part is usually includes personnel who participated in the project, equipment, budget and so on.
- Results. Sum up the data of the whole project in this part. It can include charts and figures to visualize your results in an effective manner.
- Discussion. The discussion section is about commenting results. In small documents results and the discussion part can be combined into one section.
- Conclusion. Sometimes readers, particularly managers, don’t read the whole document to save time. So you need to provide a summary of the main results and other key points of the document.
End matter
End matter provides useful information and materials outside the main body. This end part consists of:
- References. A list of sources that you’ve used.
- Appendixes usually include materials that are not essential parts of the text like additional diagrams, tables, lists, etc.
- Index. Develop an index wisely because it should be helpful for your audience. Add to your index important subject, topics, proper names.
So, this is what the structure of every technical document looks like. While writing, keep in mind that not everyone of the potential readers may be familiar with the topic described, so make sure to follow the structure and keep your writing clear. Stick to the points above and your document will be easy-to-interpret and, as a result, helpful for the target audience.