No need to render the Section Title

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
decoy text
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
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.

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

Section Macro suppressing 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
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
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.