projectdoc Toolbox

It is often obvious that the introduction text is a description of the information of the document. Therefore the title 'Description' or 'Summary' may be irrelevant. You may suppress the rendering of the title easily.

Expected Duration
10 min
Tags
Type

Sections help authors to structure the content. These visual groupings help readers to understand the content faster.

With the projectdoc Toolbox sections also define content for transclusion. So the Section Macro effectively adds identifiers to a document fragment, typically by the title of the section.

Section Macro showing the Title

In a document a reader may already be aware of the function of a section.

In this case the generic title like 'Description' or 'Summary' may be deemed as decoy text to be avoided.

 

Readers seeking for information are happy about every word they need not read.

All text that does not contribute to the genuinely relevant information is decoy text.

Typically this is the introductory text of a section or document  that does not add anything to what is already exposed by the title of the section. In our case here we argue that there is nothing wrong with the text, but the title is superfluous.

To remove the decoy text it is possible to suppress the rendering of the title.

Section Macro suppressing the Title

The result does not loose any information, but increases the readability be removing the decoy text.

The suppression of title does not remove the reuse of the fragment. The Transclusion Macro still has access to the section by the title.

Transclusion Macro selecting the Summary

Query macros, like the Display Table Macro, may also still use the content of the section to be rendered in the result table.

Display Table Macro selecting the Summary

Resources

  • More on decoy text in Benjamin L. Kovitz' book Practical Software Requirements - A Manual of Content and Style, Chapter 13.3
  • Macros of the projectdoc Toolbox
    • Section Macro - Renders a section, if the body is not empty. Supports authors to create content, clutter-free rendering without empty sections. Allows to transclude the content.
    • Transclusion Macro - Transcludes content from a document marked with the content marker macro.
    • Display Table Macro - Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.