You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
Version 1
Next »
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.
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.
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.
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.
Query macros, like the Display Table Macro, may also still use the content of the section to be rendered in the result table.
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.