- Created by Robert Reiner, last modified on 24. Mar 2019
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 3 Next »
projectdoc Toolbox
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.
- Audience
- Iteration
- Filled
- Type
- Level of Experience
The projectdoc Toolbox for Confluence provides a number of tools 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 ask 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.
Wait, there is more: User Character
If you are dealing with use cases, you may not only need roles, but also want to use personas or extreme characters to better understand and visualize the requirements and needs of users of a product or servers. In this case you may replace the Role with the User Character doctype. The User Character document may reference a role, but it may also reference a persona or extreme character with one or more roles.
Relations
As you can see from these short descriptions, the doctypes are related to each other. The relation is expressed by properties. The value of a property is a link to a document instance.
Single 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.
Audience
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
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.
Roles and Personal Information
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.
Wait, 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.
Object
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).
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.
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.
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!
- No labels
