Hi,
We want to use Confluence to build an installation manual for our products…
We have developed an approach that I will describe later on. My basic question is: is this a good way to approach the problem, is there a better way. Are there any pitfalls that I’m not seeing?
The problem we have is: We have many versions of the same product. Each version has updates. Therefore many sections will be repeated over and over. We intend to dedicate a different space for each version of the product.
So in each space we create, or copy, many boilerplate sections that are common to every product we sell, for example the System Requirements section.
In Confluence, using macros, we can create a master page and then include the sections that we need using these macros {include} {excerpt} or {multi-Excerpt}..
But each version of our product has slightly different requirements.
We are able to manage this by using the {show-if:label=xxx} macro to add in extra information that might be part of this release or version but not others.
So, here's an example:
If a new product runs on Windows we add label=windows, if it runs on Mac we add label=mac. Note: the label needs to be added at the level where the content was created, not at the level where it was included.
So basically this is how it might look:
Page: SystemRequirments
{multi-excerpt:name=all}
Common Requirements for all systems
{show-if:label=windows}
Requirements for Windows based system
{show-if}
{show-if:label=mac}
Requirements for Macintosh based system
{show-if}
More Common Requirements for all systems
To include this in a page we say
Page:home
{multi-excerpt-include:pageTitle=LiceningAgreement|name=all|nopanel=true}
{multi-excerpt-include:pageTitle=SystemRequirments|name=all|nopanel=true}
Information specific to this release.
..
..
We could use {mutli-excerpt} name capability to split a page into different sections.
But how to manage this:
Let’s say we come up with a new product. We take our existing space and copy it to a new space. This copys all the page, with their labels.
This gives us the basic structure and all of the boilerplate blocks including our System Requirements page.
These are the issues:
-Since the labels are evaluated at the level of where the pages are written and not where their used, you have to copy all of the boilerplate pages into a new space for this section of the documentation.
- We now need to visit each one of the Boilerplate pages to update the labels.
- It appears that we can support nested pages using the {multi-excerpt} macro
- It appears that we can pull these pages from other spaces. But this is of no use since the labels need to be at the level the page was created and therefore pages from other spaces can’t be reused.
- We found a macro that would allow us to manage labels “Confluence label Management plugin” but it does not run with current versions of confluence.
So that’s it. If anyone has any better ideas, please let us know.
