Starting with the projectdoc Toolbox might be intimidating at first. So start small using the basic features and add what is needed, when it is needed.
projectdoc Document
A projectdoc document has properties and sections.
Properties
You define properties within the Document Properties Marker Macro in a three-column table.
The first column contains the name of the property, the second the value. The third column stores controls that influence the value in a given context. For instance, the hide control will suppress the rendering of the property within the table.
Think of properties as data and metadata of the document. Properties do not need to be simple values. Typical properties are short description, subject, and categories. They may also contain an image, like a project icon. For specific documents, like a user story, there may be properties like the story points or the business value of that story.
You may hide individual properties or the whole table at once, if you do not need some or all metadata on the top of the page.
Use the hide parameter of the Document Properties Marker Macro to hide the whole table.
Please note that hidden information is still on the page and can be accessed by anyone with access rights to the page. Therefore it must not contain sensitive information!
Sections
Sections form the body of a document. Sections consist of a title (which can be hidden) and text. Sections may be nested and are defined with the Section Macro.
For Confluence pages authors typically add headings and text without additional macros. This is fast and easy. So why should you bother with sections?
If authors need to have the content accessible through transclusion, they need to mark it. Confluence provided the Excerpt and the Excerpt Include Macro for this. projectdoc takes this idea to the extreme and recommends to put any content inside a section. The title of the section is the default identifier to be used by the Transclusion Macro and the Transclude Documents Macro. The first macro allows multiple transclusions from one specified document while the latter allows multiple transclusions from multiple documents that are identified by a query.
The use cases for these macros may not be obvious at first sight. Here is one example use case for each of the two macros.
Transclusion Macro: A decision document may contain information about what has been decided, the reasons for the decision and a list of alternatives. Besides this there may be further sections containing detailed information, why a particular alternative has been rejected. It may also list the experts that decided and reference material they used to decide. In an overview document an author may only be interested in the decision, the reason, and the list of alternatives. The Transclusion Macro allows to do that.
Transclude Documents Macro: Assume the last use case but now you want to list the information of all decision documents that are tagged with the term "software architecture". The Transclude Documents Macro will fetch each matching document and renders only the sections containing the decision, the reason, and the list of alternatives.
Create projectdoc Documents
Creating a projectdoc document is very simple.
From scratch
Provide Document Properties- Create a blank Confluence page
- Add the Document Properties Marker Macro
- Add a three columned table to the body of the macro
- Mark the first column as table heading column
- For each section add a Section Macro
No support for Ancestor Queries!
From-scratch pages do not support ancestor queries!
To support these queries you need to define a blueprint (see From a Page Blueprint).
From a Template
This is basically the same as "From scratch" except that in step 1a you create a new template instead of a blank page.
- Provide Document Properties
- Create a new template
- Add the Document Properties Marker Macro
- Add a three columned table to the body of the macro
- Mark the first column as table heading column
- For each section add a Section Macro
New documents are then based on this template.
No support for Ancestor Queries!
Plain templates do not support ancestor queries!
To support these queries you need to define a blueprint (see From a Page Blueprint).
From a Page Blueprint
Blueprints are templates authors employ via wizards that support to provide basic information.
New documents are based on such a blueprint. As with templates, the default properties and default sections have already been added.
projectdoc provides a large number of blueprints in form of projectdoc doctype add-ons. These are available on the Atlassian Marketplace (ready to install) and on Bitbucket (in source to adjust and build by yourself).
Support for Ancestor Queries
projectdoc documents provided with page blueprints support ancestor queries!
