A better way to create product documenation, with labels, {multi-Excerpt} and {hide-if} macros
Asked by Mitch Balsam:

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

<br />

> 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.


Answers:
author: Kevin Buchs
body: I get the impression that the number of boilerplate pages is less than 50. I would suggest that you create the boilerplate pages so they each contain all the variable content they might need. Just embed it right on that page. Then use the {show-if} along with lablels on just those pages to control what shows. This will make it easy to copy the content and then you can just toggle the labels as needed. You might attach a label "boilerplate" to those pages. Then you can search on that when you fork a new space and make your checklist of pages to visit. Ctrl-MB1 to open each in a new tab and you are done in a flash.


author: Mitch Balsam
body: Manual will be 50-70 pages long. We will have 3 variations to start.

My guess is that it there will be the normal hiearchy of pages and that the, License and system requirments will be on this first page. But there might other boilerplate section to be incldued. I could see some tutorial sections in common between each product variation.

Just so you know, i have a software development background, so i approach all problems as thought its a program, so this might be overkill.

But I've also used systems like RoboHelp and have found that you always want to do things like i've described, or you will have to spend hours updatding each release..


author: Kevin Buchs
body: To help you think outside the box, I would suggest this [page](/questions/8969/how-to-handle-unique-page-names-in-confluence?page=1#8982) and [this one](/questions/9308/how-to-organize-our-software-documentation-within-confluence?page=1#9347).


author: Kevin Buchs
body: Ok, I'll bite on this one even though I don't necessarily have better ideas (yet).

Can you tell us how much content you expect to have. Are you wishing to assemble just one page for each product, which is built of the include/excerpts or more than one?

Is there a reason not to just control the content on the home page (or how ever many you answer for the last question) instead of including from other pages?

Maybe you would spell out the structure a bit more..., i.e.

Home Page contains:

License

Sys Requirements

...

Other page...


author: Mitch Balsam
body: I guess since noone has commented on this, its not a popular way to do things??


Tags: label

macro