You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 4
Next »
Categories provide easy navigation. The category page documenting the category automatically lists all documents tagged with this category. A defined set of categories has per default no such homepage.
Browsing documentations is supported by many tools. One of them are document types support navigation by linking to documents. An information model defines categories of different types that are used to label documents. Navigation is possible from a document to its categories and each category document lists all documents labeled with this category.
A document provides no means to link to a document that lists all documents tagged with two different types. The Space Index doctype mainly serves navigation purposes. The document provides links to related information. Therefore this doctype can be used to add indices to a space to list documents matching a combination of categories. The overview is still two clicks away, but at least it exists!
This tip shows how to create such an index document.
Navigating by one Type Property
Navigating by a single type property is straight forward: the property is a link to tth type, rendered with the document it belongs to.
Standard Categories
The projectdoc Toolbox provides a number of standard categories that are supported by all doctypes.
| Doctype |
Short Description |
Property |
| Subject documents allow to set document instance of different doctypes in a common context. | Subject |
| Categories allow to set document instance of different doctypes in a hierarchy. | Categories |
| Document the semantics of a tag. May also be used to document Confluence labels. | Tags |
Each document instance of these types provide a section named 'Documents' that lists all documents associated with a given category.
Doctype-specific Types
Typically all doctypes provide a property named 'Type' to reference an instance of a doctype type document. These types are doctype-specific. That is in contrast to the standard categories shown above that are provided by all doctypes, these doctype-specific types are only supported by a single doctype.
Type doctypes typically also provide a section named 'Documents' to list documents of the given type.
Other Doctypes
All doctypes can be used to categorize documents. The use of Role or Experience Level may seem more natural to categorize documents than Resource or Stakeholder. But ist basically depends on the information model which categories make sense and which do not.
Navigating by multiple Type Properties
Navigating by multiple type properties requires one additional document. This document defines a query to show documents associated with all type properties.
Then we need to specify links to this special document.
Space Index Document
While the section for type doctypes is rendered per default, space index documents to list documents with a given set of categories need to be created manually.
This example lists all documents with the subject projectdoc and the Todo Type named 'Release'.
The Subject is set to projectdoc, the Todo Type Constraint references the Release document of type Todo Type.
For this case we require to list all upcoming and previous releases.
The Display Table Macro for both sections is very similar.
The only difference is the NOT instead of an AND for listing upcoming releases instead of those that have already been accomplished.
$<Subject> = °${Subject}° AND $<Type>=°${Todo Type Constraint}° NOT $<Iteration>~[finished, production, released, deprecated]
$<Subject> = °${Subject}° AND $<Type>=°${Todo Type Constraint}° AND $<Iteration>~[finished, production, released, deprecated]
The part to select documents of the given subject and todo type is quite straight forward. Note the degree sign indicating that not only documents with the given subject and todo type are requested, but also all documents tagged with one of their child subjects and child todo types.
Type Document
The latest type doctypes support rendering related indices. This is a section with a Display Table Macro to list all Space Index documents that declare using that type as a constraint.
The Where clause for the Display Table Macro looks like this:
$<Todo Type Constraint>=[${Name}]
Therefore the macro lists all documents that reference it by the property Todo Type Constraint. This naming convention uses the name of the type (Todo Type in the example) and append the suffix ' Constraint'.
Here is an example of the rendered section of a Todo Type named 'Release'.
Non-Type Document
Doctypes for documents that do not document types this special feature is not supported per default. Therefore authors who need to render a link to the space index document have to add this manually.
Add a link manually, either in the Resources section or as an additional property.
Alternatively add a section to related indices and add a Display Table Macro with a Where clause to select on space index documents that list document of this type (just like the section type documents provide per default).
