Today we added a new tip on
with the projectdoc Toolbox.
The tip lists features that help to reuse metadata and sections with transclusion (or excerpts in the Confluence lingo).
Teams need to use their resources wisely. Customers of software often value new features more than qualities that are not so easily perceptible. And this may hold true for all industries.
One of these qualities that are neither easy to explain to customers nor achievable without team effort is evolvability. What keeps the product owner in the position to quickly respond to changes on the market?
It boils down to have a good metaphor for your software, its architecture and artifacts. A good metaphor allows effective communication, supporting to demand minimal documentation.
Minimizing resources spent for documentation by reuse is one option. But reuse is a two-edged sword. You may hurt your project with two sides if you are reusing code without a strategy to evolve the modules and interfaces. The same is true with the reuse of documentation. You have to define the modules for reuse and - as a team - keep an eye on which documents are reusing which modules.
The projectdoc Toolbox defines documents as Confluence pages with properties and sections. Information from properties and sections can be easily transcluded with a number of macros in the toolbox. While properties are simply referred to by their name, sections may be identifier by their title (which may be overridden by a stable identifier) or tags.
There are many use cases where authors may want to transclude multiple content from one document or from multiple documents. The projectdoc Toolbox handles required adoption of the heading levels of the transcluded content.
For more information on this topic, please refer to the tip Content Reuse.
