Form follows function. So authors usually expect freedom on how the document is structured to pass the information effectively to the reader. But on the other hand the reader expects similar information to be presented similar. The reader should also not notice which author has actually written the document. Therefore authors need tools to help them to align the new document with the existing documentation and the expectation of the readers seamlessly. A template can help. But we must not force the authors to follow the structure of the template mindlessly. The authors are still in charge to create the structure that delivers the information best, but the template is a guide to allow the authors to follow if no better solution is at hand. Here are some structures a template defines that are usually best kept in sync with other documents. - Properties of document types
- Names of properties
- Values of properties
- Order of properties
- Sections of document types
- Name of the sections
- Order of the sections
Usually these rules can be followed without any negative influences on the readability.The authors must not be forced to follow this structure. If a value of a property is not available and not important for comprehension, it must be left off. If a specific section is irrelevant or may not provide further understanding, it is important to leave it blank. Do not add any decoy text. If a paragraph, sentence, or even a single word does make the point clearer then drop it. In some cases it may also add to the understanding of a document, if sections are set in a different order or the content of several sections is written to one with an individual title. Last but not least we are not writing to win the Pulitzer Prize for literary achievements. There are certain kinds of documents that are best consumed if they follow a rigid structure. Glossary items do not gain much appreciation if every entry presents its information in an arbitrary sequence. Meeting minutes are best parsed by readers if they follow a predefined structure. Every document that comes in numbers, that are aggregated in a number of views benefit the reader if they are similarly structured. |