Hoping for a more robust "include page" or "include excerpt"

[Dylan Maxwell]

I'm streamlining docs for my team with templates.
I'm struggling with the Include page and Include excerpt tools

There are two three principles at play here. 

1. Docs should be simple to author (i.e. not overly long or complex with nested macros)
2. Docs should preserve commenting functionality
3. The source of the doc content should be clear and accessible

My issues are these

1. any "include" prevents commenting on the source
2. linking the "include" is a several step process
3. "include excerpt" will only use the first excerpt

My solutions

1. An "include children" macro. which will click through to the child page. Each child page can be parented to automatically add to the parent
2. the "Include page" should have an option to click through to the original location
3. the "include excerpt" should have a variable Key to call a specific excerpt from the page rather than just the first one
4. all  "include ..." macros should be combined to one macro to allow adaptability.
   
   
   

Thanks for considering the above.

[Nic Brough -Adaptavist-]

Welcome to the Atlassian Community!

Just to run over the solutions

1. I assume you don't mean "child page" - an include macro can draw in any page, not just children of the current page?
2. Yes, I know what you mean, it would be nice to be able to quickly jump to the source, my preference here would be to have it as a third option when you highlight some text  (so "create Jiras | comment | move to source page").  And I'd like the commenting to work by putting the comment on the source page directly (if the user has permission)
3. See https://marketplace.atlassian.com/search?query=multi-excerpt
4. would make the macro even more unwieldy than they are now

[Dylan Maxwell]

1) no, I mean children.  i'm hoping for a level of automatic inclusion through parenting.

• instead of a single complex page there could be a structure like this. 
  
  • top page with "include children" macro
    • snippet page a
    • snippet page b
    • snippet page c
• the "include children" would not need editing if "snippet page c" gets archived and "snippet page d" gets added.
  
  

2) I hear you. As long as commenting goes to the source, I'm happy.

3) looks great. I'll ask our admin his thoughts.

4)I hear you. The added benefit of having all the options in one macro seems good to me but I know how it is when users feel overwhelmed. Point taken.

[Nic Brough -Adaptavist-]

1) Ok, that would make the include macro useless for most people.  You need something totally new.

There is a way to get close though - use the "children" macro with "show excerpt" enabled.  

[Dylan Maxwell]

Agreed, it would need to be it's own thing if it wasn't an option (disabled by default)

But a new macro does sound fine and superior to the children with "show excerpt." 

[Nic Brough -Adaptavist-]

Yes - I do see a lot of uses for the macro you really want to have here.  I'm not an Atlassian, I have no say, but I do want to ask them for so... many... improvements. 

And this is one of them. 

Anew macro really feels like the right answer here.

(FWIW: I don't think Atlassian would ever give me a job, I don't think they would like that my customer focus is so different from theirs)

[Dylan Maxwell]

heh. Thanks for the feedback and suggestions. 

[Katerina Rudkovskaya _Stiltsoft_]

Hi @Dylan Maxwell,

You can try to use Table Excerpt/Table Excerpt Include macros of the Table Filter and Charts for Confluence app (try it free):

The excerpt source for the Table Excerpt Include can be not only a current page or a specific page, but also a page and its childpages, page and all descendants, pages with labels. 


You can show page meta data in Table Excerpt Include like this:

- page
- parent page
- space
- labels
- excerpt
- author
- last modifier
- created

BR,
Katerina

[Dylan Maxwell]

thanks