Versions Compared

Key

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

...

Section
titleRelations

As you can see from these short descriptions, the doctypes are related to each other.

Relations

Section
titleDocument Properties

The relation is expressed by properties. The value of a property is a link to a document instance.

The following diagram shows the properties of the discussed document types which reference documents.

Document Properties

Tip Box

Tools to implement such a relation typically are

  1. Name List Macro,
  2. Display Document Property Macro, and
  3. plain Confluence links.
Section
titleSingle Value - Organization Property

The Person doctype defines a property named Organization. The value is the name of the organization with a link to the document describing the organization. This link only exists, if the document actually exists.

A person is typically linked to exactly one organization. If you need to add multiple organization, you may do so. The model suggests to add the main organization and create a Stakeholder document for each further organization, the person is a member of.

Section
titleAudience Property

Each projectdoc Document has per default a property named Audience. The value for this property is a list of Role names. Each name is a link to a document describing this role.

Section
titleParticipants Property

Document properties may link to documents of different doctypes. The Participants property of an Event document is an example for this. Each Event document describes an event in a journal. Participants of an event may be Persons, Stakeholders, and Organizations.

Section
titleRoles Property and Personal Information Property

The Stakeholder document instance maps a Person document to a set of Role documents. The Person document is referenced with the Personal Information property. Users can navigate to description of roles via the Roles property.

Note Box
titleWait, there is more: Association

The Association is a generic doctype that allows to document an association. Its purpose is to use it in an information model to be able to reference two document instances and describe the relationship. And as with any other doctype of the projectdoc Toolbox, the association may be tagged with metadata, such as Association Type (by the Type property), Tag (by the Tags property), or Roles (by the Audience property) – to name a few. An association is therefore a named and documented link between to documents.

Section
titleObject Property

The Object property of the Event doctype allows to reference anything on the internet, the intranet, or beyond that is a representation of what this event is about. It may be a ticket on JIRA, a reference to an e-mail, an article on a blog or a URN of a book (such as an ISBN).

Note Box
titleReferences Section

If the information is backed-up by a number of references, those references are typically listed in a Tour Macro in the References section of the document.

Section
titleDocument Sections

Each property defines a relation in one direction. The referenced document may list all documents where its name is mentioned in a dedicated section.

The following diagram shows the sections of the discussed document types which lists documents that mention the document instance with one of their properties.

Document Sections

Section
titleExample

The Audience property lists the name of Roles for whom this document is relevant. From the other side, the Role document lists all documents in a section where the role is specified as Audience.

The following screenshot renders the documents relevant for the role Documentation Architect.

Screenshot of the start of a Role document showing documents targeting at it

Tip Box
titleAvoid long Lists

While the section is part of every document, some documents may list a very large number of documents. Rendering such a page will take quite some time. Besides its caches for document properties the projectdoc Toolbox currently provides no services to speed up the rendering of large lists.

Please bear in mind that these lists are used for navigation. Very long lists may make navigation very difficult for your users. It is therefore advisable to reorganize the hierarchy of tags if those lists get too long.

It is recommended to keep lists lengths around 100 entries. But the performance of the rendering process depends on a number of factors and users may work happily with longer lists according to your use cases. So your mileage may vary.

Section
titleBehind the Scenes

The Display Table Macro is used in the Section Macro with title Documentation.

Section Macro and Display Table Macro in the Page Editor

The Display Table Macro automatically collects all resources, tours, and topics with the given audience and lists the Name, Short Description, Doctype and Audience property.

Display Table Macro in the Macro Editor

Tip Box
titleManually Selection

You do not want to use a query, which is resolved at request time, but present a hand-selected, fixed list of links? Have a look at the Tour Macro!

...