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.
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.
|Focus||Confluence Macros||projectdoc Toolbox Macros|
|Properties||Page Properties Macro|
|Excerpt Include Macro|
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.
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
Transclude Documents Macro allows to define queries to match documents by their properties and then transclude sections from the documents in the result set.Especially for index documents or glossaries authors may need to transclude sections from a number of documents. The
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.
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
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.
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.
More information on transclusion and related topics:
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!