Technical documents have a common structure as they contain the same elements. The elements help technical writers organize their content in a logical structure for easy navigation. The elements are collectively known as the format. A well-organized document is useful for readers as it is easy to understand the purpose of the document and find the relevant information. Technical documents are a part of both the hardware and software industries. Certain naming conventions of the elements vary across these industries. For example, the hardware industry uses the convention Materials and Apparatus, whereas the software industry uses the convention Software Tools and Applications.
Technical documentation is divided into three parts that are further divided into the elements it contains.
Figure: Parts of Technical Documentation
The front matter contains the purpose of the document. This increases the usability of the document. From this section, readers can know what the document is about, who created the document, why to refer to this document, how to navigate through the document, what topics they can look for in the document, and where they can find information of their interests.
The elements of the front matter are described in the following table:
|Title Page||The title page gives an exact idea of what is covered in the document. The title of a document should be clear and specific.|
|Abstract||Abstract provides a brief summary of the document. It should be a page or less. It provides clear information about the subjects or issues, methods used to resolve issues, main results, and conclusion of the document. This helps the reader to understand the purpose of the document.|
|Table of contents||The table of contents contains headings of the topics in the document. It helps the readers to navigate through the document to find the information of their interest. Documents with more than ten pages should have a table of contents.|
|List of figures||The list of figures contains the names of the images in the document. It is a useful element as readers refer to images and charts frequently to quickly understand the idea. A list of figures helps readers navigate to the visual information easily.|
|List of tables||The list of tables contains the names of the tables in the document. It helps the readers to quickly refer to the information created in a tabular format.|
|List of terms||The list of terms contains terminology, acronyms, and abbreviations mentioned in the document. Readers can refer to this element and find the full form or meaning of a term.|
|Acknowledgments||Acknowledgment contains the names of the people, such as developers, fellow technical writers, and colleagues who provided assistance to complete the document.|
The body of the document contains information on what steps have been taken or which methods have been used to meet the business goals or resolve the issues mentioned in the abstract. The objective of the body is to convince the reader, create trust, and document actions to resolve the issues.
The elements of the body are described in the following table:
|Introduction||The introduction gives an idea to readers about the scope of the document, background information, what to expect from the document, the issue addressed in the document, and the importance of addressing the issue.|
|Background||The background provides the history of the issue, a summary of previous research on the topic, and reasons for creating the document.|
|Theory||The theory describes the formulae and techniques used for explaining any complex features and functions|
|Design criteria||Design criteria contain proposals, feasibility reports, recommendation reports with the possible design of a product or a future course of action.|
|Materials and apparatus/Software tools and applications||Materials and apparatus/Software tools and applications contain the list and description of all hardware and software used for the experiment or procedures explained in the document.|
|Procedure||The procedure describes methods or experiments for gathering data. The procedure should be written in narrative form with illustrations so that readers can perform the tasks.|
|Workplan||Work Plan describes the future actions of the project plan. The project plan includes information on how a project will be conducted, who will participate in which part, when and in what order will each part be achieved, what equipment will be used, what will be the budget of the project, and so on.|
|Results||Results include charts and figures that summarize the outcome of the actions performed.|
|Discussion||The discussion explains the information mentioned in the Results element. It includes comments on important data produced by the study.|
|Conclusion||The conclusion provides a summary of all crucial information necessary for the readers. Some readers sometimes do not read the entire document and concentrate on the conclusion.|
The end matter provides useful auxiliary information to the readers.
The elements of the end matter are described in the following table:
|References||References contain a list of sources that the author of the document has used for creating the document.|
|Appendixes||Appendixes provide useful reference material such as additional diagrams, tables, lists, and so on.|
|Index||The index contains search terms that help readers find the locations of applicable information in the document. You must add important subjects, topics, and proper names to the index.|
While writing a technical document ensure it has a structure as explained in this document, and the content is concise and easy to understand for the readers.
Author, Rohini Sharma, Technical Writer Trainee, Metapercept Technology Services LLP