Tricks of the trade?

[Cameron Smith]

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]

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

[Dirk Lachowski]

We’re using Scroll Viewport by K15t for most customer facing documentation. It’s a marketplace app that builds a static website from one ore more Confluence spaces and that comes with integrated search. 

Works great, looks ok and the customer service is really responsive. 

[Kristian Klima]

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

[Angela Thomas_Seibert Group]

Hello @Cameron Smith

When creating customer-facing documentation from Confluence pages, people often get confused choosing between public links and anonymous access feature and seek help from community. The answer has always been to make your space public in Confluence with anonymous access. Here's why:

You can read the longer guide here: https://seibert.biz/anonymous-access-vs-public-links-guide

Enabling anonymous access for customer-facing Confluence spaces allows users to explore the entire space without login barriers. However,  please bear in mind that the native Confluence elements such as the breadcrumbs, space settings, page history, and comments will also remain accessible.

For confluence cloud, you can control what can be published. I would like to direct your attention to Spacecraft app. The app can turn a Confluence space into a slick website with a sidebar on the left. The end result would look a lot like this user guide that is powered by Spacecraft. You could also add multiple Confluence spaces to one site.

[Yulia Lenina _AppFox_]

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!:)