To make it easier for readers to determine the relevance of a document, there should be short description for each document.
Finding the information within the project documentation may be tricky. Queries may return a list of resources. For the stakeholder looking for a piece of information a link labeled with the title of a document may not reveal enough information to determine the relevance of the result.
How can we increase the navigability of link lists and search results?
How can we help readers to understand quickly if a document is relevant to them or not.
Structure
Describing the content supports readers to determine if a document is relevant for them without starting to read the document. There are two kinds of descriptions:
- Short description: typically one to three sentences long, plain text
- Description: any length and employing any structure and graphics that fit
Short descriptions are used to provide additional information in dynamic lists and in search results. In case that the title of a document is not enough to understand the contents of a document, the short description is quite handy. Since this information is displayed in the context of other documents and their titles and short descriptions, this information should be similar worded and structured.
Descriptions are typically rendered on top of documents. They describe what the document is all about. This is not the same as a summary which should support readers to get the most relevant facts or to help them reminding the contents of the document. Although the descriptions may also be displayed in the context of other documents, it poses no restriction on its contents, structure and layout options.
Advantages
- Readers are supported to understand which documents are relevant to them more quickly.
Disadvantages
- Writing descriptions requires resources. Dropping descriptions in favor of short descriptions, which may be easier and cheaper to write, may help to save resources.
Related Practices
The following practices are related to this practice.
Resources
For more information regarding this practice please refer to:
