You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 2
Next »
Do not render text to the reader that has no information value.
A team needs to maintain the documentation for a product or project collaboratively.
How can the team ensure that the information from their documentation can be consumed by readers easily? Even despite the fact that documentation is continuously evolved.
Structure
Noise is visual garbage that distracts the reader without giving any useful information. Examples for such noise are:
Keep in mind that the reader is happy for every sentence s/he does not need to read.
Authors should remove noise and be sensible for the problem of superfluous content that transmits no valuable information.
The projectdoc Toolbox provides tools to reduce the noise in documents. The Section Macro defines the structure of a document but do not show up if empty. It can also be hidden if the section is not yet ready to be displayed to the reader. The rendering of the title can be suppressed for sections whose function is obvious from the location in the document in order to reduce decoy text. Properties within the Document Properties Marker Macro also do not show up if there is no value (or can also be hidden). Properties may also control which sections are shown.
Advantages
Document without noise are easier and quicker to read. Since reading occurs more often, the additional investment for removing noise is almost always a good idea.
Disadvantages
For inexperienced authors removing noise typically takes more time. To reduce this resource investment these authors should work with a professional or pair with more experienced authors to catch up quickly and with more fun.
Resources
For more information regarding this practice please refer to: