How to build a product documentation solution in 30 minutes

[#1]

Yes! You can built a full-fledged, end-to-end, scalable product documentation and management solution using Confluence and a couple of apps. 

In 30 minutes.

Note: In this article, I only plan to provide the outline of the setup. Time permitting, I’ll deep-dive into the specifics in subsequent articles.

Target features

• Proper functional workflow

• Ready for continuous delivery 

• Minimal content dependencies

• Conditional content (not permission-based)

• Single source authoring

• Automatic content backups

• Edits and Published history

• Two documentation sites - public and internal 
• Google analytics integration

• Great SEO

• On your own domain(s)

• With your own branding

• SAML SSO for the internal site

• No public Confluence spaces (no anonymous access)
• Have your cake and eat it too

The goal is to have a setup where you have two documentation sites, on your own domain. One site is public, one is for your internal use and features stuff you don’t wanna share. Now, of course you want the internal site behind login - ideally under your corporate SSO. You want to do all your work in a single space to avoid duplication and ensuing chaos.

You’re on a continuous delivery bandwagon and you want to publish the docs updates wherever they’re needed, even several times a day, but at the same time you need to work on drafts and edits, sometimes for weeks.

Here’s what you need

As some of you know, the above is the setup I deployed at Emplifi. And it was a major factor behind our success. There are alternative setups, one of which, that I tested, is described further down in this piece.

• Confluence (you already have that :) )

• Two spaces - lets call them Source and Target - no need to enable anonymous access

• Comala Document Approval

  • a simple workflow app that you enable in Source

• Comala Publishing

  • It syncs your finalized Source content to Target - on a page-to-page basis. And it converts the links from Source to Target.

• Scroll Documents with Variants

  • Extends the concept behind what a space is and what a space can do

  • Handles conditional content - choose which page, section of a page (paragraph, sentence, image) appears in the public site and which is internal only

  • You create identical setups in Source and Target

• Scroll Viewport

  • Creates a full-fledged documentation portal

  • Your own domain

  • Your SSO

  • Google analytics

  • SEO optimized

What do you get?

Ultimate control over your content and freedom to update your documentation sites independently of whatever’s happening in development - while keeping closely aligned to it via Jira. 

At Emplifi, we’re using this very setup for our docs. At any given moment, we can have 50 pages that we work on, enjoying full benefits of Confluence collaboration. At the same time, we can publish ANY page, updated or new, at any point in time pretty much without dependencies.

It saves us a lot of time, we don't fight content conflict battles, and helped us optimize processes behind our docs - writing and the docs life-cycle management.

30 minutes

And can you set up the whole infrastructure it in 30 minutes? Absolutely. I did it several times. With just a couple of clicks.

Yes, you need to know what you're doing and come prepared and synced with your IT/DevOps. But 30 minutes is doable.

Alternative apps

• Confluence page status (as a workflow app)

• Space Sync for Confluence (to sync Source and Target spaces)

• Pages Manager for Confluence (free app to manage statuses and syncs)

Note: There are, of course, other apps with more sophisticated approach to workflows and approvals :) And they would greatly expand options of this setup. The ones above are the ones that I tested.

Why did I write this…

I often fight a lonely Confluence battle in the Write the Docs Slack community, standing between the rock of DIY open source aficionados and the hard place of galactic-scale docs CMS. My point is that you don’t have to scout Stack Overflow to figure out how to code in some rudimentary functionality, nor do you have to pay an arm AND the leg for a tool that has a 1998 GUI and of which you use 20% of the features.

I interact with writers (and others) in the SME segment complaining about the cost of Confluence apps only to go out and buy a $20K a year tool. Case in point, I presented my set of requirements to a major docs CMS vendor. I got a quote for $32,000 - for 4 (as in four) full author seats. I'd still have to pay for webhosting (about $4-5K a year for TWO sites) or built my own solution. And I’d have zero Jira, or any other work management tool, integration. 

To compare, my setup costs less than $10K for 50 full seats with Confluence Premium and I'm managing 5 Viewport sites.

I may be preaching to the converted here :) But hey, in the last two months, I helped two writers I met on forums create a version of my setup. And I’m kind of proud of that :) 

So I decided to do this write-up and, hopefully, a couple of more detailed followups, as an inspiration and to start a brainstorming discussion.

[Barbara Szczesniak]

Thank you for this, @Kristian Klima. Over the last 18 months your contributions in this community have helped me tremendously with my own setup for my documentation. 

[Kristian Klima]

@Barbara Szczesniak Oh wow, thank you for this, I'm really glad you find it useful.

[Stavros_Rougas_EasyApps]

This is really useful post. It would have saved me time. Our docs run on Scroll Viewport.

I hear you on the cost complaints. Reject Confluence and then go on and hire or buy an expensive tool. This includes those already with a Confluence license, for them it would only be a matter of buying one or two apps.

This leads me to an underappreciated part of Confluence that saves time and money - it's generally easier to maintain, especially if you are already using Jira.

I know this post is mainly focused on setup. Great documentation starts with a good base and evolves, in part based on feedback in support (more like wow why are people confused, we thought it was clear). Evolve meaning to both grow and stay up to date.

Too often when it is decided how to create documentation maintenance is not given enough weight. This is a reason we chose to use Confluence and not WordPress for our docs. Maintaining content is why we built Space Content Manager, a suite of bulk content editing tools. It's a bunch of little things over time, and Confluence as a wiki allows one to do it at scale which saves times and improves accurately.

[Kristian Klima]

@Stavros_Rougas_EasyApps Thank you! 

And I couldn't agree more on Confluence - Jira integration and the dangers of reducing documentation to typing the text.

I deployed the whole docs LCM process around DocOps methodology. Documentation is a part of the product, writers are embedded into dev teams, doc tickets are part of those teams epics, stories, etc. To many people, this is doc-as-code, but most of the time it means using Git based tools for writing and a lot of headache. 

With the setup above, yes, it's put together from multiple components but the setup, changes, and maintenance is a question of a couple of clicks. And then you can focus on content instead of wasting time on fighting your tools and/or using the tools that are sandboxed from each other... or connected with 'connectors' that require maintenance, setup, LCM...