projectdoc Toolbox

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.

Parent
Level of Experience
Expected Duration
20 min
Tags
tutorial, projectdoc, add-on, Confluence, Atlassian
Type

There is just one rule to follow to always have the full potential of the toolbox ready to be unleashed:

The one rule

To get
the full potential of the projectdoc Toolbox
make sure that
every Confluence page is a projectdoc document

To follow this rule you need just these two macros:

  1. Document Properties Marker Macro
  2. Section Macro

This short tip shows what a projectdoc document is, how it can be created with those two macros and provides some tips to new users on how to continue working with the projectdoc Toolbox.

Contents

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

  1. Provide Document Properties
    1. Create a blank Confluence page
    2. Add the Document Properties Marker Macro
    3. Add a three columned table to the body of the macro
    4. Mark the first column as table heading column
  2. 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.

  1. Provide Document Properties
    1. Create a new template
    2. Add the Document Properties Marker Macro
    3. Add a three columned table to the body of the macro
    4. Mark the first column as table heading column
  2. 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!

What is next?

Using projectdoc documents will provide you with all the power you need for working with the projectdoc Toolbox. Here are some topics to increase your fun and success!

Overwhelmed with Blueprints?

The large amount of blueprints may be intimidating. But if some blueprints exist that makes the work of a team easier? We recommend that you get a general idea what is available. The blueprints are organized in sets.

Core Doctypes
Provides a basic set of doctypes to create agile documentation.
Doctypes for Software Development
Provides doctypes to create documentation in software development projects. The focus is on documenting the architecture of the product, but it includes templates for other software development documentation requirements as well.
projectdoc Add-on for arc42
Provides doctypes to document a system or software architecture based on the arc42 Template.
Doctypes for Agile Planning
Provides doctypes to collborate with your team. Run iterations and record discoveries that may be of interest at the end of the iteration or for even later reference. Quick notes are more easily added as records to the team's space than to the official documentation tree. Defer the talk to the documentation architect to the end of the iteration (if the discovery is still of interest).
projectdoc Developer Diaries
Provides doctypes to organize the developer's work by the employment of a diary. Take you personal planning and professional records to the next level!
projectdoc for Java Developers
A collection of blueprints for Confluence to create and work with documentation for Java projects.
projectdoc for Maven Developers
A collection of blueprints for Confluence to create and work with documentation for Maven projects.
Doctypes for Teamwork
Provides doctypes to define the checklists, processes, patterns, tools, and rules your team agrees upon. Writing them down makes them accessible for anyone - especially for new team members. Keep these documents short and to the point!
Doctypes for Business Strategy
Mission, vision, strategy for business planning and execution.
Doctypes for Service Management
Provides doctypes to document services and systems for IT service management (ITSM).
Doctypes for Project Management
Provides doctypes for documenting decisions, risks, open issues, and meeting minutes.
Doctypes for V-Modell®XT
Use products (templates) from the V-Modell®XT in your Confluence wiki as blueprints!

 

A team typically selects a couple of blueprints they decided to use in their work. In Overwhelmed with Blueprints? we describe how the team can focus on these selected blueprints.

Learn the basics

To learn more about the projectdoc Toolbox, take your areas of interest from the following list of introduction materials:

projectdoc Introduction
A short introduction into the concepts and features of the projectdoc Toolbox.
Hands-on Tutorial
Get started with the projectdoc Toolbox: learning by doing
Basic Concepts and Conventions for projectdoc
Concepts central to projectdoc. Things users have to understand to get the most out of using projectdoc.
Tour for Document Authors
Tour through the documentation for users who want to learn to create documents based on projectdoc doctypes.

Read the Tips

We provide a growing list of tips to show interesting aspects of the working with the projectdoc Toolbox.

Delve into more Topics

For more information on the projectdoc Toolbox browse the list of topics or pick a macro.