- Created by Robert Reiner, last modified on 10. May 2017
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 4 Current »
Build a navigation to related and associated information by the use of document properties and dynamic linking.
- Domain
- Type
- Principles
To enhance the navigability of a documentation documents need to reference related information. This supports readers who lack information to specify a successful query to find relevant information by browsing.
Structure
Provide a query that matches all documents that provide related information the readers are interested in.
To do this successfully some information architecture work is required. A team should settle on a number of tags and categories they describe and use coherently. While a good information architecture needs a lot of thought (and experience does no harm), teams in a agile environment typically do not have much time to spent on this topic. Good news ist that these teams do not need define the perfect ontology. Their domain will grow with their knowledge of their domain. Therefore do not strive for perfection but instead go with what works now and probably tomorrow.
For each document decide if you can specify a query that matches related documents. This is usually harder than one might think. If none of the documents are tagged, this will violate the Open Closed Principle, since the authors need to add metadata to existing documents. If you have developed a sound information architecture, this will be much easier.
Advantages
- Dynamic links will automatically reference related information. This safes resources since these lists do not have to be hand-crafted.
- Existing documents do not need to be altered, so the authors can concentrate on the document they are writing.
- The query always reflects the current set of related links.
Disadvantages
- The authors have no control over the links that will end up in their document. If other documents are not tagged properly this list may show links that do not apply and fail to render links that would be helpful.
- Authors have no control over the order of links. While dynamic links allow to define a sort order, this order may not be the best choice for the document at hand. While the authors may open the referenced documents to apply an additional sort order, this would violate the Open Closed Principle. In this case the static Tour Macro may yield better results and support authors in providing property information from the referenced documents.
Variants
Dynamic links are sometimes called dynamic lists or automatic lists.
Related Practices
The following practices are related to this practice.
- Categorize
- Organize content by keywords.
- Describe Content
- To make it easier for readers to determine the relevance of a document, there should be short description for each document.
- Dynamic Links
- Build a navigation to related and associated information by the use of document properties and dynamic linking.
Resources
For more information regarding this practice please refer to:
- Display Table Macro
- Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
- Display List Macro
- Lists references to projectdoc documents in a list. List contain names and optional short descriptions.
- Transclude Documents Macro
- Renders transcluded content fetched from documents of a result set.
- Document Properties Marker Macro
- A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.
- Document Properties Supplier Macro
- A table containing additional document properties. Three columns: name, value and meta data (aka controls) to a property.
- Document Properties Supplier Attachment Macro
- A table supplying additional document properties from an attached file.
- Search Tips
- Tips on specifying search queries for Lucene. This also applies to projectdoc's query macros.
- No labels
