Advice on organization/features for documentation

I keep posting questions on how to do certain things, but I think it might be better if I described how I want to use Confluence and solicit ideas from people.

We want to use Confluence for authoring documentation for clients. These documents would usually be assessments, but may also be runbooks, or documentation of the work we performed. When an assessment is scoped, there are some common things that are included, and there are some things that are unique to the client.

Right now, I'm using MS Word to write documentation. I have a basic template with the common things in it, then I manually go and find other prewritten content and copy/paste it into the document in the correct places. Then I go through and edit everything I need to make that content specific to the client, and writing additional information as required. It's a huge pain in the butt.

So, I'm testing Confluence right now. I created a space for each different group that does documentation. My plan was to have a page for each client, and then do a tree of subpages for the document. I might have a page tree that looks like this:

  • - WizzyCorp Assessment
  • -- Copyright
  • -- Executive Summary
  • -- Findings and Recommendations
  • -- Technical findings
  • --- ProductA
  • --- ProductB
  • -- Appendix

This is very simplified from what the actual tree looks like. Basically each section is a subpage in the correct part of the tree. When I export it with Scroll PDF, I export the whole tree and it generates a nice document for me. Also, by having separate pages, multiple authors can edit at the same time. The problem is, you cannot have duplicate page names in a Space. So if I have another client (there will be hundreds), I can't name a page "Copyright" since it's in the Space for a particular documentation team.

Another problems I'm running into is that I created an Inclusions Library, but that only works to link the content to my document. To make changes to the linked content, I have to modify the content in the inclusions library, and that would modify the content in ALL documents that was linked to it. I don't want that. I need a way to essentially take content from my Inclusions Library and automatically paste it into my working document so I can make changes to it. If there's a way to do this with an add-on or writing a macro, please tell me how, because I'm at a loss. It looks like I can do Blueprints for this, but a Blueprint creates a whole new page and won't allow me to insert content inline to an existing page. This would be fine, but due to the restriction on duplicate page naming, it looks like I'm going to have to move away from doing a page sub-tree, and put my document all into a single page.

This leads me to my next question, is there a way to view the outline of the document based on header levels, and a way to move them around without copy/paste? I'd like to view the header hierarchy, and be able to drag/drop my headers to reorganize them along with the content under each one.

Basically, here are my basic requirements:

- Being able to easily pull in reusable content and NOT have it linked to the source so I can edit it to be unique for the document I'm working on. I'm guessing this will involve writing a macro that essentially pastes in content from my Inclusions Library, or putting all of my content in Blueprints and figuring out how to get the blueprints to paste inline rather than creating a new page. Unfortunately, if I go the Blueprints route, there's no good way that I can see to organize the Blueprints. I have hundreds of different topics for reusable content, and that's going to get really messy and be a huge pain to scroll through them all when an author is looking for what he needs.

- If duplicate page names are NOT an option (WHY?!?!), I need to be able to have authors be able to easily view the outline/header hierarchy within a single page. Even better if they can drag/drop sections around, and expand/collapse sections to view or hide the content under each header. The InPlace editor allows editing of just the section under each header, but doesn't provide this other functionality.

I've been thinking about these problems for the past month, and I haven't come up with a good solution yet. Any thoughts or ideas?

1 answer

Hi Jay,

a few comments:

* Duplicate page titles: If you concerned about duplicate page titles in the PDF export, you can use the a scroll-title macro for that (see http://www.k15t.com/display/OFCE/Overwriting+Confluence+Page+Title). Otherwise, Scroll Versions can help (https://marketplace.atlassian.com/plugins/com.k15t.scroll.scroll-versions).

* Including Content: It looks like you want to copy the content, right? Currently, you can open Tools > View Source on the page you want to copy and copy/paste the content. It's an interesting requirement to have soming like "insert page content" (a.k.a. boilerplate) in the editor, but I am not aware of a plugin that does this.

* Modifying the outline of a page: Not aware of a solution yet. We recommend our consulting clients to keep pages short, to make the content more fine granular.

Hope this helps (a bit),
-Stefan

Suggest an answer

Log in or Sign up to answer
How to earn badges on the Atlassian Community

How to earn badges on the Atlassian Community

Badges are a great way to show off community activity, whether you’re a newbie or a Champion.

Learn more
Community showcase
Posted Jul 10, 2018 in Confluence

We want to see the templates you've created in Confluence!

Hi Community, Jessica here from the Confluence Product Marketing team!  July’s community challenge is all about sharing pictures  — and as an extension of our first post on what ...

670 views 21 12
Join discussion

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you