Tricks of the trade?

Question

Hi all,

Looking at creating both internal and customer-facing documentation for our "Freight as a Service" platform. Pretty sure I can get through Confluence with the documentation and community's help.

As I start this journey, are there any words of wisdom you'd be able to share? Things you might wish you knew before you started. Hurdles you've had to jump that might have been easier another way.

Thanks, Cam

Barbara Szczesniak · Answer

@Cameron Smith My biggest piece of advice is to figure out how you are going to present your content first.

I spent a lot of time putting in TOC macros on my pages and using layouts to organize my content (and working around several lacking features in Confluence that they later sorted out 😒).

Then we decided to use Scroll Viewport to present our content to our internal customers, rather than giving everyone a Confluence license. This is a much better way to control the content for them, but I then had to go back and redo a lot on my pages that I didn't need or wasn't supported in Viewport.

I would also recommend the K15t Confluence Collaboration Hub as a good resource to learn about Confluence.

Yulia Lenina _AppFox_ · Answer

Hi Cameron, great question!

I can share our own experience working with internal and external documentation as an app vendor, plus experience of our customers we're working with.

I would highlight 3 key areas here:

* Keeping track of the status of a document
* Managing Access
* Making docs live at the right time

Keeping track of the status

It's crucial to know the actual status of the document - is it in progress? Approved? Awaiting approval? Awaiting your approval? Published? Outdated?

All this can be done with our app "Workflows for Confluence": setting up the workflows for documents, assigning approvers, tracking expiration, etc.

Managing Access

Here, we use ourselves and recommend our customers as best practices, to use separate spaces for draft, approved docs for internal teams, customer-facing documents. This way, we make sure that the right people have access to the drafts, while internal teams see the final and approved version. The same goes for customer-facing documents. Workflows for Confluence can manage that and automatically publish docs to another space, once they're approved.

Making docs live at the right time

For this purpose we at AppFox, and our customers too, use Scroll Viewport by K15t. We publish our customer-facing docs using this app.

Hope it helps!:)

Kristian Klima_gtcuat · Answer

Hi @Cameron Smith and welcome to the Community.

We have a similar setup at Emplifi - an internal and a public doc space

Oh, disclaimer - I'm a customer of Atlassian and app vendors I mention here :)

Anyway, we have a single Confluence space and then use dedicated apps to build to distinct sites.

* Scroll Documents + Variants 
* Scroll Viewport (all apps by K15t)

Scroll Docs and Variant allows us to use labels to designate which content appears in which site (I discuss conditional content in my article here on community - it's very detailed and touches on the subject of public/internal too).

Then we use Viewport to build the sites from Confluence content. One is public, the other is internal and can only be access via our SSO.

The reason for this is that Viewport doesn't need spaces with anonymous access and we can control access to the internal site via SSO - so even our folks without a Confluence seat can access the site.

I discuss the setup in another article: https://community.atlassian.com/t5/Confluence-articles/How-to-build-a-product-documentation-solution-in-30-minutes/ba-p/2875027

Anyway, even if you decide for a different solution, the articles are still useful to give you a general idea of what you can achieve.

If you want to learn more, feel free to ask questions or ping via LinkedIn to chat (for free :)  ).