Provide views on your topic-based documentation.

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.

How can we organize documents so that it can be easily found from different contexts?

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.

pattern

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Structure

Advantages

Disadvantages

Related Practices

Resources

About

Keep up-to-date!

Powered by