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.
Writing modular documentation is not an easy feat. Creating a long document is easier than a short one. Trapping one information in one topic is hard. Creating a documentation based on lots of topics is for skilled writers. In a project environment, where we create documentation by the team for the team, we are not looking for perfection. Still we need tools to organized the information in topics of different sizes and employ tools to help us to reuse this information.
Transclusion also helps to create documents independently. A team working on a task may create a document collaboratively by writing each chapter of the document in individual topics. These chapters may further be divided into sections, each on its own wiki page. The document is assembled of all these parts by transclusion. Once a fragment on a page is changed, the changes are reflected immediately on the transcluding document. This document can be exported easily.
The building blocks of a modular documentation are documents. The building blocks of documents are properties (defined by the Document Properties Marker Macro) and sections (defined by the Section Macro).
You may even replace placeholders in the content while transcluding.
Transclusion made easy
Why easily? Suppose an author transcludes content from another page. In view mode the transcluded content is highlighted. By clicking on the name of the document at the top-right of the box, the author is able to jump to the page quickly. If clicking on the edit icon (pencil), the document is opened for editing with one click.
For performance reasons the fragments may be cached. In this case every transcluded content shows the last updated date and an icon to refresh the content from the cache (although the system typically recognizes stale content quickly).
Tools for Writers only
Note that these tools are only available for authors since readers typically have no interest in getting informed about content reuse.
If an author is interested in where a particular content is used, the information can be displayed on the page easily.
The projectdoc Toolbox also provided macros to make these sections only available for authors. But note that the content is only hidden and therefore not secure.
For more information on transclusion, please refer to Use Display Table for Transclusion References.
Just in case if you are bothering about transcluding content with inadequate section levels. Do not bother. The transclusion macros of the projectdoc Toolbox take care of adjusting the levels of the sections to the target level. For Confluence 5.8 and up this can even be done automatically!
Since version 1.10 of the projectdoc Toolbox you may even transclude tagged content from a document automatically and add additional sections and properties to the transcluding document. This feature is called delegate document. The delegate document is defined with the Document Properties Marker Macro.
More Information on Transclusion
- Content Reuse - 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.
- Use Display Table for Transclusion References - It is easy to list all pages that transclude a section from the current page. This allows you, as an author, to check quickly if changes to a document that is transcluded, needs changes to the transcluding documents.
- Excerpt and Transclusion - Explains the differences between and commonalities of the Confluence Excerpt and the projectdoc Toolbox Transclusion features.
- Working with Transclusions - Compare the excerpt feature of Confluence with the transclusion feature of the projectdoc Toolbox.
- Remote Transclusion - Lists features of the projectdoc Toolbox according transclusion of text content that is stored on remote information system. Macros to transclude content provided by Confluence out-of-the-box are compared to these features.
Define content to transclude
- Section Macro - Renders a section, if the body is not empty. Supports authors to create content, clutter-free rendering without empty sections. Allows to transclude the content.
- Content Marker Macro - Marks a piece of content within a document. This content can be referenced for transclusion.
- Document Properties Marker Macro - A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.
Transclude text blocks
- Transclusion Macro - Transcludes content from a document marked with the content marker macro.
- Transclude Documents Macro - Renders transcluded content fetched from documents of a result set.
- and many more to transclude content from outside the wiki ...