Although some degree of freedom and variability is allowed and found, the writing and processing of technical documentation typically follows universally accepted and appreciated rules that can be used as a reference point. These rules apply to both technical documents (such as reports and user manuals) and scientific documents (such as theses and scientific articles in journals or conferences). First among them is the organization of the document into 3 parts:
- Front-matter,
- Main-matter (or document body),
- Back-matter.
The front-matter includes the most relevant and reference data of the document, such as title, sub-title (if any), name of the author(s), and possibly its (their) information such as email address and/or affiliation (entity/company affiliation). In the case of technical documentation, elements such as version history of the document in tabular form (e.g., v0.1 first draft, author XX, …), copyright information, liability (and also confidentiality) statements, and others may also be included in this part. A widely used but optional element is the Acknowledgements section, which is included in this part in the case of technical documents or theses, whereas scientific papers include this (optional) section in the back-matter. On the other hand, elements of fundamental importance and almost always present are (in order):
- the list (or table) of chapters (or sections, or contents),
- the list of figures,
- the list of tables.
Such lists (or tables) should be made by cross-referencing, thus aiding the reader in understanding the structure of the document and providing it with quick links to multiple points in the document. Exceptions to this are scientific articles in which such indexes are not present, but in which mandatory sections such as the Abstract and the list of keywords find their place. Keywords are indications of the pivotal topics on which the work presented is based.
For each of the document types, the central part, or body, is unique and follows the same rules. This part includes the main content of the document, which is usually distributed in several chapters (or sections). Each chapter (or section) is numbered following a progressive numbering. Each chapter (or section) may contain multiple sub-chapters (or sub-sections), even on multiple nested hierarchical levels: these will be indexed following a progressive and hierarchical numbering. For example:
- First chapter
1.1 First sub-chapter of the first chapter
1.2 Second sub-chapter of the first chapter
1.2.1 First sub-chapter (or third-level chapter) of the second sub-chapter (or second-level chapter) of the first chapter
1.3 Third sub-chapter of the first chapter - Second chapter
…
This numbering is then reflected in the table of contents, typically following an indentation based on chapter and sub-chapter level.
Scientific papers present a peculiarity concerning the body. It is a common and widely used practice that the first chapter is called the Introduction, and the structure and contents of the other chapters are given in its concluding part. Indeed, this type is the only one that does not include the table of contents. An example is as follows: “The remainder of the paper is organized as follows: Section 2 describes …; Section 3 illustrates …; Section 4 reports the results; finally, Section 5 presents the conclusions of this work.” Similarly, the last chapter is usually called Conclusions (or Discussion, or both are included, using Conclusions as the last chapter). This, or these, are usually preceded by the Results chapter (or section).
References to other documents (which will be part of the Bibliography section, in each case included in the back-matter), as well as figures, graphs, tables, and equations, and references to them within the text, may be included to support the content of the document, distributed throughout the various chapters and sub-chapters. Each of these elements follows very specific rules.
- Bibliographic references. They are inserted within the text to cite the corresponding document in the bibliography, using square brackets: e.g., “[3].” Typically, the reference number alone is used (or a range of numbers, if referencing multiple bibliographic sources in sequential order, such as “[4-9]” to indicate all bibliographic documents from [4] to [9], extremes included). Therefore, typically in a document you will be able to find phrases such as “In [1] it is specified that …”, or, “… as indicated in [7].”, and so on. You should never use the form such as “In reference [2] …” unless the reference number is at the beginning of a sentence (or an aside). For example, “[2] shows that …” is wrong, whereas the correct form is “Reference [2] shows that …”; similarly “… as evidenced in the corresponding documents, [4] and [9], i.e. …” is wrong, rather the correct form is “… as evidenced in the corresponding documents, references [4] and [9], i.e. …”
- Figures (and Charts). All figures must be numbered and have a caption that must be placed UNDER the figure. The caption is intended to succinctly indicate the meaning of the figure, whereas the numbering of the figures should be progressive and hierarchical, according only to the numbering of the first-level chapters. For example, the first figure within the first chapter will have the index 1.1 (or 1-1), the second 1.2 (or 1-2), and so on; the first figure within the second chapter will have the index 2.1 (or 2-1), even if it is the first figure in the entire document. Exceptions are scientific papers, in which case the figures follow a purely progressive numbering without connection to the chapter numbering. In addition, all figures must be referenced in the text obligatorily before their inclusion, and they may be freely referenced elsewhere in the document without restriction. Cross-references in the form “Figure 1.2 shows …”, or “as shown in Fig. 1.2” are used to reference a figure. Graphs are a special type of figure characterized by the presence of axes of representation. These must follow all the rules given above for figures, and, in addition, each axis must be associated with a label (relating to the measured quantity) and a unit of measure enclosed in ROUND brackets as shown in Figure 1.
- Tables. Tables follow the same rules as figures, except that the associated caption must be placed ABOVE the table.
- Equations. Equations are typically numbered incrementally without including chapter (or section) hierarchy level, and they can be referenced by simply using the corresponding index in round brackets, such as “as expressed in (2),” or by also using the word “Equation(s)” or “Eq.”: e.g., “as indicated by Equation (3).” The same rules used for bibliographic references apply in the case of the only-number reference, i.e., it is mandatory to use the word “Equation” or “Eq.” in case the reference is at the beginning of a sentence (or an aside).
In general, whether the references are to bibliographic sources, figures, graphs, tables, equations, or other parts of the text of the document, it is necessary to always use precise cross-references and NOT generic references such as “as given in the table below” or “as illustrated above,”. Rather use references such as “as given in Table 3.2” or “as illustrated in Section 1.2,” because this makes the document clearer and more precise, and avoids possible ambiguities.
Concerning the back-matter, this should always contain the Bibliography section (sometimes called References, especially in scientific articles). However, it is not strictly required within technical documents, although it is strongly recommended to include it whenever possible because it makes the document more reliable and increases its rigor. As anticipated, in the case of scientific papers (in journals or conference proceedings), the back-matter can accommodate the (optional) Acknowledgements section, which, on the other hand, must be integrated into the front-matter in the case of technical papers or theses. Another optional section that can be present in the back-matter of scientific papers is the Funding section, which can be inserted instead of the Acknowledgements section or together with it. A final optional section is the Appendices section, and it follows the same rules for each type of document. One or more appendices can be inserted, and they too can include multiple sub-sections on multiple hierarchical levels. Therefore, the numbering of appendices (and their sub-sections) follows the same numbering used for chapters (and their sub-chapters) as well, with the exception that the first level of numbering adopts capital letters of the alphabet instead of numbers. For example:
A. First appendix
A.1 First sub-chapter of the first appendix
A.2 Second sub-chapter of the first appendix
A.2.1 First sub-sub-chapter of the second sub-chapter of the first appendix.
B. Second appendix
…
In any case, the Appendices section should ALWAYS be inserted AFTER the Bibliography.
Concluding this post is Table 1, which provides a summary of the various elements that can (or should) be included within a document, depending on the type of document.
Table 1. Summary of required and optional elements for writing a technical or scientific document. Elements enclosed in round brackets indicate optional elements, whereas the others are to be considered mandatory.
| Element | Reports, manuals, … | Thesis | Scientific papers |
|---|---|---|---|
| Front-matter | Title (Sub-title) Author’s/s’ info (Versions history) (Keywords) (Copyright) (Acknowledgements) (Disclaimer) Summary/List of Contents List of Figures List of Tables | Titolo Author’s/s’ info (Acknowledgements) Summary/List of Contents List of Figures List of Tables | Titolo Author’s/s’ info Author’s/s’ affiliation Abstract Keywords |
| Body | Chapters/Sections with progressive numbering Sub-chapters/Sub-sections with progressive hierarchical numbering | Chapters/Sections with progressive numbering Sub-chapters/Sub-sections with progressive hierarchical numbering | Chapters/Sections with progressive numbering Sub-chapters/Sub-sections with progressive hierarchical numbering |
| Figures | Progressive hierarchical numbering Caption BELOW | Progressive hierarchical numbering Caption BELOW | Progressive numbering (without hierarchy) Caption BELOW |
| Tables | Progressive hierarchical numbering Caption ABOVE | Progressive hierarchical numbering Caption ABOVE | Progressive numbering (without hierarchy) Caption ABOVE |
| Equations | Progressive numbering | Progressive numbering | Progressive numbering |
| Back-matter | (Bibliography) (Appendices) | Bibliography (Appendices) | (Acknowledgements) (Funding) Bibliography (Appendices) |