You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
Version 1
Next »
Build a navigation to related and associated information by the use of document properties and dynamic linking.
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.
How can we add references to related information that may not even exist at the time of writing to support 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.
Resources
For more information regarding this practice please refer to:
