Structure

Noise is visual garbage that distracts the reader without giving any useful information. Examples for such noise are:

• Decoy text is text without information such as

  • Titles for sections whose function is obvious
  • Intro text that describes what is obvious
• Skeleton text are text fragments where information may be added at a later time (this noise is typically introduced by templates)
  • Section titles without section body
  • Documents with only auto-generated content without information
  • Dead links which are not recognizable as such
• Tedious representation (compact representation would be easier to recognize with one glance)
  • Two-column tables instead of definition lists
  • One-element lists
  • Short descriptions as part of the metadata

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: