Templates to guide Authors

Style already defined

A decision that is already made: the layout of the page. Authors in a wiki typically do not need to bother with this. There is one, sometimes more, templates for applying styles. Even if there are more than one, it is usually pretty clear which one to apply in a given situation.

Structure somewhat defined

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 the author needs a tool to help her to align the new document with the existing documentation and the expectation of the reader seamlessly. A template can help. But we must not force the author to follow the structure of the template mindlessly. The author is still in charge to create the structure that delivers the information best, but the template is a guide to allow the author 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 author 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.

Content marginally defined

If the information in the document is not genuine, there is no entitlement for it to exist. So there is no constraint on the content with the exception of controlled vocabulary and probably a style guide. Again this is necessary to provide a consistent documentation for the reader with the least surprise according style, structure, and content.