Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Document Properties Marker
overridefalse
Short DescriptionIt 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.
 

Doctypetopichide
NameNo need to render the Section Title
 

Parent
Parent Property
propertyParent
property-nameName
hide
Audience
Name List
doctyperole
render-no-hits-as-blanktrue
propertyAudience
 

Level of Experience
Name List
doctypeexperience-level
render-no-hits-as-blanktrue
propertyLevel of Experience
 

Expected Duration
 
10 min
Subject
Name List
doctypesubject
propertySubject
 

Categories
Name List
doctypecategory
propertyCategories
 

Tags
Tag List
namesdecoy text
propertyTags
 

Iteration
Iteration
valuefinished
hide
Type
Name List
doctypetopic-type
render-no-hits-as-blanktrue
namesTip
propertyType
 

Sort Keyhide
Section
titleDescription
 
Section
show-titlefalse
titleSummary

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.

Info Box

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

...

Section
titleResources
  • More on decoy text in Benjamin L. Kovitz' book Practical Software Requirements - A Manual of Content and Style, Chapter 13.3
  • Macros of the PDAC1
    • Display Properties
      documentSection Macro
    • Display Properties
      documentTransclusion Macro
    • Display Properties
      documentDisplay Table Macro
Piwik Set Multiple Custom Variables
NameValue
Departmentprojectdoc
Categoryprojectdoc-tip
Typehowto