- Created by Robert Reiner, last modified on 12. Nov 2019
projectdoc Toolbox
Tools from the projectdoc Toolbox to allow users to browse for information.
- Audience
- Type
- Level of Experience
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.
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.
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.
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).
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.
Homespace
A homespace is the single point of access to the wiki and all remote resources attached to it.
Homespaces
The homespace is not necessarily an index space.