The projectdoc Toolbox makes it easier to create links for navigation for users to browse the documentation. This tip explains some the concept in the context of organization, person, role, and stakeholder.
The projectdoc Toolbox for Confluence provides a number of tools (especially macros and doctypes) to add links to a document to create a web of documents. This is important as users of a documentation have fundamentally three ways of finding information
- Searching
- Browsing
- Asking
Searching is using a search engine to find relevant documents by stating a couple of properties as a query. Asking is the opportunity to consult an expert for a solution. Both are not in the focus of this tip.
In the context of not knowing exactly what the solution would be, probably not knowing any keywords to use for a search, browsing makes it possible to eventually find the answer. It enables users to start with a document that is distantly related to what they look for. By clicking from one document to the next, the users are gaining knowledge in a new domain. It is also useful after a search that almost answers the question of a user, but valuable, additional information is just one click away or this click explains concepts, the user has not fully understood yet.
This short tip introduces the solution for navigation provided by the projectdoc Toolbox by the use of the Organization, Person, Role, and Stakeholder doctypes.
Doctypes
Doctypes provide information in form of document properties and document sections. Properties are simple key/value pairs, sections provide information in blocks of text, each with an optional heading.
For this example the following doctypes are used.
- Organization
- An organization document provides information about an organization that is relevant for a project. Typical properties are the name, logo, address, and website. Sections include a description of what the organization does and why this is important for the project, a list of contacts working for this organization or publications this organization has made.
- Person
- A person document provides information about a person that is relevant for a project. This includes the name, contact information via various channels, and maybe a photo as document properties. Sections may include information about skills and resources of this person that is relevant for the project. It may list meetings the person has participated, publications the person has made.
- Role
- A role is a description of what people in this role are doing. It may provide the required skills, responsibilities, tools they use, and requirements they impose on a product as document properties. In sections the document may list use cases or processes this role participates or documents of the wiki that are relevant for this role.
- Stakeholder
- Persons have different roles in one or more projects. The Stakholder doctype maps a person to a role in the context of one project. This makes it easier to have the more constant information in a Person document and provide project specific information to Stakeholde document that transcludes the relevant information from the Person document. So typically most personal information is transcluded. But the person may have a different e-mail address for a project as a document property. The listed meetings the person attended in the context of a project may be limited to the meetings that are relevant for that project.
Relations
As you can see from these short descriptions, the doctypes are related to each other.
Relations
Document 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
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.
Audience 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.
Participants 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.
Object 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).
Document 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
Example
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.
Behind the Scenes
The Display Table Macro is used in the Section Macro with title Documentation.
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.
Wrap up
From an abstract view we see different kinds of relations:
- Single value relation:
- Defined type: Like the Organization, the value of a property is a single value having a predefined type
- Any type: Like Object
- Multiple values relation
- Same type: Like Audience the value is a list with all element sharing the same doctype
- Different types: Like Participants the value is a list, with each member having a doctype from a predefined set
- Any type: There is currently no example for this in the projectdoc Toolbox, but you can imagine an Objects property that links to a number of documents of any type
Documents may act as a mapping document to relate two or more documents by a name, description and additional metadata.
Document sections also support navigation by the use of the Display Table Macro or the Tour Macro.
The free doctype add-ons of the projectdoc Toolbox provides examples on how to use document types and document properties to design the information model that best suites you team or organization. Please check out the source code for these doctype add-ons as a basis to build your own!
Resources
Here is a list of resources for more information on tools and concepts used in this tip.
