Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Document Properties Marker
doctypetopic
overridefalse
Doctypetopichide
NameWriting Short Descriptions
 

Short DescriptionBenefits of and tips on writing short descriptions.
 

Parent
Parent Property
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
namesNovice
propertyLevel of Experience
 

Expected Duration
 

Tags
 

Iteration

Iteration
value

filled

finished

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

Sort Key0000200hide
Section
titleDescription
 
Section
titlePrerequisites

...

Section
titlePurpose of Short Descriptions

Short descriptions help users to identify, whether a document contains relevant information.

Within projectdoc query result table entries and automatic lists are typically used to render references to documents with their short descriptions. You may also use the Display Document Properties Macro with a template to show the name and short description of a document.

Documents listed in a Display Table with Name and Short DescriptionImage Added

Section
titleGuidelines for Effective Short Descriptions

Laura Bellamy, Michelle Carey and Jenifer Schlotfeldt have collected the following guidelines for writing effective short descriptions in their book

Cite
template$[Name] (${Publication Date})
documentPDAC:Bellamy2012
:

  • Briefly State the Purpose of the Topic
  • Use Complete, Grammatical Sentences
  • Don't Introduce Lists, Figures, or Tables
  • Keep Short Descriptions Short
  • Avoid Writing Short Descriptions That Are Self-Referential
  • Don't Simply Repeat the Topic Title

...

Section
titleReferences
  • Cite
    template$[Name] (${Authors}; ${Publication Date})
    documentPDAC:Bellamy2012
Section
titleResources
Tour
render-as-definition-listtrue
replace-title-with-nametrue