projectdoc Toolbox

Tools from the projectdoc Toolbox to allow users to browse for information.

Audience: Documentation Architect, Documentation Gardener, Template Author, Author
Type: Tip
Level of Experience: Advanced Beginner

Finding information includes searching and browsing (see Finding without Searching for more information on information architecture) .

This tip shows the different tools on four levels – macro, document, space, and site – provided by the projectdoc Toolbox to support users finding information by browsing.

Contents

At Macro Level

Many macros of the projectdoc Toolbox support rendering links. Links can be created dynamically or set manually.

Dynamic Linking

There are a couple of macros to support dynamic linking. Dynamic linking allows authors to define queries to list links to related documents.

The Display Table Macro allows

to select properties and sections from the result set (select)
define a query to match document (where)
and define an order of the documents of the result (sort by)

The elements of the result set are rendered as links to related documents.

Similar to the Display Table Macro are

Display List Macro: Lists references to projectdoc documents in a list. List contain names and optional short descriptions.
Display List Template Macro: Lists references to projectdoc documents in a list. List items are defined by templates referencing properties.
Transclude Documents Macro: Renders transcluded content fetched from documents of a result set.

The Wiki Link Macro allows to render a link only if the target document actually exists.

Manual Linking

Links to related documents can also be hand-crafted. Since projectdoc allows to define document properties that may be helpful for readers to be rendered with the link to the document, the projectdoc Toolbox provides a set of macros to do so.

Tour Macro: Renders a predefined list of documents in a table.
Tour-by-Property Macro: Renders a predefined list of documents in a table . Documents are selected by a document property. Allows to select document properties for columns. Also non-list representations are provided.
Display Document Properties Macro: Renders a template with property references.
Cite Macro: Renders a cite to a resource document.

Tour Macro in editor as an example for Manual Linking

One List to list them all

If you need to render links from manual and dynamic links in one list, use the Table Merger Macro.

At Document Level

At document level the projectdoc Toolbox allows to render links to point to other documents.

Document Properties

Document property value may be links to other documents. These documents often list all documents that link to them.

The value of a property must not be a dynamic link!

This is due to the fact that the value of a property is stored in the Lucene index at the time the page is saved. Dynamic linking is resolved at request time.

Standard Categories

Standard categories, like Tags, Categories, Subjects allow to categorize documents – see Finding without Searching - applied! for details.

Since version 9.x of the Core Doctypes, Tags, Categories, and Subjects also allow to define types. This allows authors to group standard types.

Type-specific Types

Further categoization is provided by type specific type using the Type Property (for instance Resource Type , Role Type , or Topic Type ) – again, see Finding without Searching - applied! for details.

Each type can be organized by the standard types. Therefore Resource Type , Role Type , or Topic Type, too.

Parent Property

The Parent Property is a reference to the semantic parent of the document. This navigation option is often redundant since the breadcrumbs allow users to find the parent page quickly. Therefore the property is often hidden per default.

The parent property may be useful when accessed for link rendering purposes.

Other Properties

Properties often link to documents of other types.

Here are some examples:

The Audience Property and the Roles Property (of the Stakeholder Doctype) point to document of type Role
The Experience Level Property (of the Topic Doctype) points to documents of type Experience Level
The Authors Property (of the Resource Doctype) points to documents of type Person
The Publisher Property (of the Resource Doctype) points to documents of type Organization
The Experts Property (of the Charter Doctype) points to documents of type Stakeholder

This allows authors to define a web of documents that are easily navigateable by readers.

Note that instances of every doctype may be used as a value for a property and therefore provide a navigation path from one document to another.

Document Sections

Besides links at any location of a document there are sections dedicated to list sets of references to other documents.

References: For a document the references section contains pointers to resources that prove the statements of the document.
Resources: Provides references to further information to the topic of the document.
Children: Organizing documents in a hierarchical manner is sometimes very helpful to help readers to orientate in the documentation. The children section automatically lists the child documents, usually with the name and short description.

Since these sections are standard to each document, it is easy for readers to locate links to related documents.

At Space Level

Pages of a space link documents and support navigation within a space.

Space Homepage

Space homepages with a lot of links are created by space blueprints provided by doctype add-ons.

Example of a space homepage

Index Pages

Per default page blueprints provide index pages that list all documents of a given type.

Example of an index page

Homepages

Per defaul doctyps provide homepages that list all top-level documents of a given type.

Example of doctype homepage

Space Index Doctype

The Space Index Doctype allows to create documents to list links to related documents.

Space index documents may also actually host documents as their children. But this is usually discouraged since it makes it more difficult for authors to find the correct location for a new document (see Single Sourcing).

Example of a space index page

Homepages and index pages are actually of type Space Index, whose doctype ID is docsection.

At Site Level

There are a number of tools that link documents in different spaces and thereby support navigation within a site.

Index Space

Index spaces support browsing at space level.

Index spaces contain standard categories to tag documents
Index spaces may list the main spaces of the site

Typically there is one index space that is the root of a hierarchy of delegate spaces.

Example of root index space

Homespace

A homespace is the single point of access to the wiki and all remote resources attached to it.

Example of a homespace

Homespaces

The homespace is not necessarily an index space.

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java