You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

projectdoc Toolbox

Short Description
Benefits of and tips on writing short descriptions.
Level of Experience
Iteration
Filled

Purpose 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.

Guidelines for Effective Short Descriptions

Laura Bellamy, Michelle Carey and Jenifer Schlotfeldt have collected the following guidelines for writing effective short descriptions in their book DITA Best Practices (2012):

  • 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

When not to use Short Descriptions

In case where users do not require additional context information for a link, do not use short descriptions to save space.

So if in a given context the label "Homepage" says it all, you do not need to add the short description. For projectdoc the site homepage for a team usually does not need the short descriptions since the team is working every day with it.

Layouts with and without Short Descriptions

 

The old layout used to render short descriptions on the homepage. A lot of space is dedicated to these descriptions which are hardly read by the developing team. New team members probably do not benefit from the short descriptions either, since the link labels themselves are meaningful enough.


The new layout renders the homepage without short descriptions. This way the team has more space on the homepage to render information that is important for them on a daily basis.

Here the homepage layout for the space designed for software development projects:

 

The links to pages to create categories, tags and other document types that are most relevant for document authors are presented here. The homepage for the space (the landing page) provides only the most relevant links for readers, saving space for individual project information:

References

  • No labels