Is Include Page Macro reliable for re-using content?

[Stephen Kairys]

Confluence Server 6.4.2

Hi,

I'm designing a document that details a windows application. There are three main procedures I need to explain. While they differ, much of the content is the same. My assignment specifies that I should explicitly explain each item in each of the three procedural sections. 

e.g. (oversimplified/redacted):

Section 1

<Paragraph about how to create a widget>

Other stuff

<Paragraph about how to delete a widget>

Section 2

More stuff

<Paragraph about how to create a widget>

<Paragraph about how to modify a widget>

<Paragraph about how to delete a widget>

Section 3

<Paragraph about how to modify a widget>

<Paragraph about how to copy a widget>

Even more stuff

-----

I'm thinking. Have four small documents:

1. Create widget

2. Modify widget

3. Copy widget

4. Delete widget

Include one or more of these docs within Sections 1, 2, and 3.

Is the above a viable solution? Is this macro reliable? I have a vague memory about having an issue if the included page contained headers that would impact TOC, but I don't intend on having headers in the included docs.

Thanks,
Steve

[Shannon S]

Hi Stephen,

Are you referring to the Include Page Macro? This is reliable as it simply includes the content of an existing page into another page. However, for your use, it seems like you should use the Excerpt Include Macro. You would use this if you need to include a section of a page in more than one place.

My recommendation would be to create one document with four sections on how to create, modify, copy, and delete a widget. This way you can reference each section when you need it.

Please keep in mind that users won't be able to see the included excerpts if they don't have access to the original page. You'll want to be sure to set the proper permissions on the page that contains the content you're including.

Let me know if you have any questions.

Regards,

Shannon

[Stephen Kairys]

Thanks, Shannon.

Question:

>>My recommendation would be to create one document with four sections on how to create, modify, copy, and delete a widget. This way you can reference each section when you need it.<<

How would I "reference" each section? 

[Shannon S]

Hi Stephen,

I believe this is mentioned in the Excerpt Include Macro documentation, but you create your excerpt using the Excerpt Macro. 

I had a look more closely at the Excerpt Include Macro documentation, and I revoke my previous statement, as I see now that you can have more than one Excerpt Include Macro on a page, but only one Excerpt Macro on a page.

So your setup will look like this:

• Create four separate pages in Confluence, one each for "create widget", "modify widget", "copy widget", and "delete widget". This I believe you were going to do before.
• On each of the pages, you will insert the Excerpt Macro. Inside the macro you can write your instructions.
• Finally, in your pages where you need to reference the excerpts, you can insert the Excerpt Include Macro. When editing the macro, you type the name of the page that contains the excerpt you want to reference.

If you choose to, you could still do your earlier idea to use the Page Include Macro, but if you were experiencing issues with headers, the Excerpt Include macro should at least get rid of that problem.

I hope that's clear but do let me know if you have any questions.

Regards,

Shannon