Provide views on your topic-based documentation.
- Domain
- Type
- Principles
Information needs to be organized to be easily findable. This is not only important for readers who seek information, but also for authors who need to know what is already there and where to place a new document.
Structure
Views allow access to information from multiple viewpoints.
Views come in two forms:
- Property views
- Tours
Property views are created by the selection of documents with a given set of properties. They are purely navigation tools. Use dynamic lists to render links to related documents.
Tours are created to answer a specific question for a given audience by referencing or transcluding topics. Tours are documents built by reusing information from document modules.
Advantages
- Views compile existing information into new documents.
- Views make it easier for readers to find relevant information.
Disadvantages
- Creating views requires additional resources.
- Too many, unaligned views may actually prevent users from finding information quickly.
Related Practices
The following practices are related to this practice.
- Physical Location
- Store information physically only by properties that are invariant.
- Favor flat Hierarchies
- Organize information physically in flat hierarchies. Add views to put these documents in different contexts.
- Single Sourcing
- Reduce redundancy by having one source of truth for each information. This way the written information is more easily reusable in other documents and - which is even more important - it is referenceable. Single sourcing demands automation.
- Dynamic Links
- Build a navigation to related and associated information by the use of document properties and dynamic linking.
- Single Point of Access
- Users require a single point of access to all information relevant for a project.
Resources
For more information regarding this practice please refer to:
- Tour
- Guided tours through existing information. This allows to aggregate topics for a given question or audience, thus providing a view on a topic.
- Display Table Macro
- Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
- Transclude Documents Macro
- Renders transcluded content fetched from documents of a result set.