projectdoc Toolbox

The projectdoc Toolbox provides a number of features to help teams to reuse content. Content can be transcluded individually or in form of a multitransclude. Authors can even transclude content from multiple documents in the wiki, effectively combining transclusion with automatic lists.

Parent
Audience
Level of Experience
Expected Duration
30 min
Tags
Type
Contents

Teams need to use their resources wisely. One form of saving resources is reuse. But reuse comes at a cost. First, teams need to write content in chunks that is actually reusable. Modular writing is not easy. It requires a lot of practice and a common understanding of the information architecture and a good metaphor that communicates it. Second, teams need to keep track on which content is reuse at which location. If you need to change a module, it is usually handy - especially for team members who are no experts in technical writing - to understand in which contexts this information is used.

The projectdoc Toolbox provides macros that support teams to create agile documentation by reusing content by transclusion. In the context of Confluence transclusion is often referred to as excerpting content.

Document as the Building Block

A projectdoc document defines properties and sections. The projectdoc document is the base for most of the macros in the projectdoc Toolbox.

Properties are data and meta data of a document that teams define in tables with the Document Properties Marker Macro and the Document Properties Supplier Macro. This information is transcluded with the Display Document Property Macro and its cousins.

Sections define text to be transcluded by the Section Macro. Sections may have titles. Authors needing to refer to a chunk of content that is not a section use the Content Marker Macro. Content is transcluded by the use of the Transclusion Macro, the Transclude Documents Macro, and some related macros.

Since version 1.11 of the projectdoc Toolbox neither the transcluding document nor the document transcluded from is required to be a projectdoc document.


Compare to Confluence Macros

 

Confluence provides macros that work similar. Here is a short line-up including macros dealing with properties and sections.

While the Confluence macros are easier to use, the macros of the projectdoc Toolbox provide some additional features to make team collaboration and communication a lot easier.

For more information on this topic, please refer to Compare with built-in Features.


Tip for an easy Start

 

To get started with projectdoc we recommend to use the projectdoc Blank Document for your experiments. It provides the basic structure of a projectdoc document with properties and sections.

For more advanced use cases consider to install one or more of the projectdoc doctype add-ons (especially the Core Doctypes). Install the doctype add-ons from the Atlassian Marketplace for free. They are also available on Bitbucket for customization.

Transclusion Features

The projectdoc Toolbox supports the following transclusion use cases.

Multi-Transclude from a Document

Authors may want to transclude more than one piece of content from a document. There may be a large document with information for novice and expert users. Both audiences may need the basic information. There may be some additional facts for novice users that may be of no interest for experts. And authors would like to give some hints for expert users that may just confuse beginners.

The Transclusion Macro allows to create two documents based on one document with its content tagged as 'common', 'novice' and 'expert'.

 

Having one document with information for different audiences is not a silver bullet. It may help for some use cases, for instance if the number of content sections that is dedicated to one audience only is quite small, but not for all.

Transclude from multiple Documents

Shows an example for multi-excerpt from three documentsEspecially for index documents or glossaries authors may need to transclude sections from a number of documents. The Transclude Documents Macro allows to define queries to match documents by their properties and then transclude sections from the documents in the result set.

There are specialized forms of this macro: Index Entries Table Macro and Index Card Macro to support creating documents like indices and glossaries.

Transcluding with Heading Level

Authors often need to transclude content that is specified with a heading level of 1 to a section that is at level 2 or lower. The transclusion macros of the projectdoc Toolbox allow to specify the target level.

 

Suppose a module defines a section with two subsections at the level of one. An author needs to transclude this section to the level of two. The author simply uses the Transclusion Macro and sets the target level to 2. The section will be rendered at the level of 2, its children at the level of 3.

From Confluence version 5.8 on, authors do not need to bother with the target level. Simply specify the asterisk ('*') and let projectdoc find the correct level. If the asterisk is defined as the target level, projectdoc will determine the level at which the transclusion is specified at request time.

 

The asterisk is especially handy if you decide to move the Transclusion Macro or the Section Macro in which the Transclusion Macro is some levels up or down. With the asterisk as the target level, simply drag-and-drop!

Transclude into Table Cells

The Display Table Macro allows to reference documents in the form of a table. Authors map properties to table columns. They my also map sections to table columns.

Simply specify the name of the section as you would specify the name of a property. The value will be transcluded to the table column.

While the Display Table Macro fetches the list of documents that meet its search criteria on request time, the Tour Macro allows to render a table of documents. The author selects for each row in the table which document is rendered. The columns define the properties and sections to add.

Trancluding Document Properties

Similar to transcluding sections the Transclusion Macro, the Display Table Macro (and its cousins) allow to excerpt one or more property values from a document.

 

Currently it is only supported to transclude a property directly from a document. If that property is also transcluded, the property value will be shown, but it is not guaranteed that changes to the transient documents (that is: the not immediate referenced documents) will not be noticed by the transcluding document.

Trancluding Space Properties

Properties may be defined on space level. Using the Display Space Property Macro allows to render the value. Note that due to the delegate-space authors may define hierarchies of spaces where the properties are inheritable.

For more information on space properties, please refer to Using Space Properties.

Module Documents

Information can be transcluded from any document. If you want to define chunks of information, sometimes called topics, the Core Doctypes Add-on provides the Module document type. This doctype provides standard properties and sections.

The Transcluded by section lists all documents that transclude content from the module automatically. Use Display Table for Transclusion References explains how to do this for your own documents.

Resources

More information on transclusion and related topics:

Name Short Description
Tools to provide or consume content to support reuse.
Use rich multi-excerpts (transclusion) for content reuse - even from page result lists. Replace parameters in excerpts. Include properties and sections from pages. Hide content dependent on roles and properties.
Concepts central to projectdoc. Things users have to understand to get the most out of using projectdoc.
Get started with the projectdoc Toolbox: learning by doing
An overview over the use cases for which the projectdoc Toolbox provides support.

The projectdoc Toolbox is  available on the Atlassian Marketplace!