Templates allow to guide authors producing information of a given type. They also help readers to find the information they are looking for quickly.
How does the projectdoc Toolbox support this?
A template typically puts a demand on the author: fill out everything! Or remove what you did not fill out now! Neither is appreciated. The author has a set of information in her mind she wants to contribute. Maybe the document is created collaboratively. Certainly it is created iteratively. This especially applies to project documentation, where the team writes for the team. In this case the documentation is typically never finished. Rather the documents are in different states of the iteration cycle. Yet the information provided is already relevant for other team members. Do we want our readers to be confronted with empty sections only attached to a decoy title? Do we add value by some decoy text like "TBD"? On the other hand, if the boiler plate parts are removed, we have no access to them when we or other team mates need it.
The solution is to defer this problem to the projectdoc Toolbox:
- Properties are only rendered, if they provide a non-blank value
- Sections are only rendered, if the body has actually content
This way, the author may leave any blank property values or empty sections as is. This allows future work on the document to further rely on the defined structure.
On screen this looks like this:
In edit mode the author has access to the structure that is defined by the template. The author decides which information she needs to add to the document and stores it at the defined locations. She may add any number of additional properties or sections. Any properties or sections that are not yet (or never relevant), are left empty. Once the document is saved, only those properties and sections are presented to the reader that actually contain relevant information.
