Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Document Properties Marker
overridefalse


Doctypefeaturehide
NameTemplates 
Short DescriptionTemplates allow to guide authors producing information of a given type. They also help readers to find the information they are looking for quickly. 
Parent
Parent Property
property-nameName
 
Audience
Name List
doctyperole
render-no-hits-as-blanktrue
propertyAudience
 
Categories
Name List
doctypecategory
propertyCategories
 
Tags
Tag List
 
Iteration

Iteration
valuefinished

hide
Importance
Feature Importance
 
Sort Keyhide



Section
show-titlefalse
titleDescription

If you start a new document from scratch you have to think about a lot of things. Since you are adding a page to a wiki some of the decisions have already been made for you. Less freedom in this context is actually a good thing! Authors are experts with important information on their minds that needs to be turned into an externalized form to communicate with stakeholder and team members (including the author's future self).


Section
titleStyle already defined

A decision that is already made is the layout of the pages. Authors using a wiki typically do not need to bother with decision. 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.


Section
titleStructure 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 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.


Section
titleContent 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.


Section
titleSubfeature
Display Table
doctypefeature
render-no-hits-as-blanktrue
selectName, Short Description
restrict-to-immediate-childrentrue
sort-bySort Key, Name


Section
titleNotes


Section
titleReferences


Section
titleResources
intro-textMore information on this feature.


Tour
render-as-definition-listtrue
replace-title-with-nametrue




Section
titleMore Features

List of features of the projectdoc Toolbox for Confluence.

Display Table
doctypefeature
render-modedefinition
selectName, Short Description
sort-bySort Key, Name
where$<DirectAncestorTitle>=[Features] -Synonym:[* TO *]