Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Section


Column


Document Properties Marker
overridefalse


Short DescriptionCategories 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.
Doctypetopichide
NameNavigating Documentations
Short Name
Parent
Parent Property
property-nameName
hide
Audience

Name List
doctyperole
render-no-hits-as-blanktrue
render-list-as-comma-separated-valuestrue
namesDocumentation Architect, Documentation Gardener, Template Author, Author
propertyAudience


Subject
Name List
doctypesubject
propertySubject

Categories
Name List
doctypecategory
propertyCategories

Tags

Tag List
propertyTags


Flagsprojectdoc Toolbox, Confluence, navigationhide
Iteration

Iteration
valuefocused

hide
Type
Name List
doctypetopic-type
render-no-hits-as-blanktrue
propertyType

Level of Experience

Name List
doctypeexperience-level
render-no-hits-as-blanktrue
namesCompetent
propertyLevel of Experience


Expected Duration
Sponsors
Name List
doctypestakeholder
render-no-hits-as-blanktrue
propertySponsors

Sort Keyhide




Column
width300px


Panel
titleContents

Table of Contents
indent15px
excludeResources
stylenone




Section
show-titlefalse
titleDescription

Browsing documentations is supported by many tools. One of them are document types which support navigation by linking to documents of their type. 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.

Example Box

The Topic doctype defines a property named Type that links to an instance of the Topic Type doctype. A topic type may be Howto. A topic document of type howto set its type property to the value of Howto. The Howto document lists all topic documents of its type.

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!

Tip Box
titleInformation Architecture

Please refer to the blog posts Finding without Searching and Finding without Searching - applied! for an introduction to creating an information architecture!

This tip shows how to create such an index document.

...

Section
titleNavigating by one Type Property

Navigating by a single type property is straight forward: the property is a link to tth the type, rendered with the document it belongs to.

Section
titleStandard Categories

The projectdoc Toolbox provides a number of standard categories that are supported by all doctypes.

Tour
header-translationsTitle=Doctype


TitleShort DescriptionProperty
Subject
Subject
Category
Categories
Tag
Tags


Each document instance of these types provide a section named 'Documents' that lists all documents associated with a given category.

Example Box

The document of type Tag named 'Security' describes what this tag is for and lists documents of any doctype that are categorized with this tag.



Section
titleDoctype-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.

Example Box

A document of doctype Topic Type lists documents of doctype Topic, if their Type property matches the name of the topic type.



Section
titleOther 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 it basically depends on the information model which categories make sense and which do not.


...

Section
titleNavigating 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.

Section
titleSpace 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.

Image RemovedImage AddedThe 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.

Code Block
languagetext
titleWhere Parameter for Upcoming Releases
$<Subject> = °${Subject}° AND $<Type>=°${Todo Type Constraint}° NOT $<Iteration>~[finished, production, released, deprecated]


Code Block
languagetext
titleWhere Parameter for Previous Releases
$<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.


Section
titleType 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.

Image Modified

The Where clause for the Display Table Macro looks like this:

Code Block
languagetext
titleWhere Parameter
$<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'.


Section
titleNon-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).



...

Section
titleReferences


Section
titleResources


Tour
render-as-definition-listtrue
replace-title-with-nametrue





Piwik Set Multiple Custom Variables


NameValue
Departmentprojectdoc
Categoryprojectdoc-tip
Typehowto


...