Has anyone used Confluence to create their own company-specific style guide tor technical documentation?

[Nic Brough -Adaptavist- · Accepted solution]

I've not done it myself, but I've supported technical writers, authors and managers while they've done it.  Confluence is a good fit for it.

[Adrian Reid]

I'm with Steve. I'm a technical writer who has used Confluence in a number of organisations as well as other tech writing apps eg Adobe and I really prefer Confluence. Confluence has the flexibility to be used a number of ways not just tech dox.

There's a few issues though. It's a bit difficult to skin. You can add a company logo at the top of the page and change the theme to company colours but you need a plugin to do more than that.

If you have external and internal users on the one site it's not easy to secure pages. You can do it but it's not easy.

Also keep in mind the actual cost of Confluence is a lot more if you add up all the plugins you might need eg a visual editor like Gliffy which you might need for diagrams.

I'm just putting the negatives out there to keep things balanced, I still really recommend the application.

[Nic Brough -Adaptavist-]

I'd also add that it encourages contributions too - one place I worked a few years back basically used it for everything.  We actively encouraged people to write what they thought was needed, and also made them understand that everyone was responsible for improving their docs.  Inline comments have made that so much easier since I left, and they're going to love the collaborative editing even more.

I think you're absolutely right about the "issues".  Off the shelf, Confluence is an excellent match for what Greg (and you and Steve and I ) want, but you almost always need to look at some add-ons to extend the base product

I usually look at:

• Theming, especially if you're going to throw it out to non-internal users.  Refined and Brikit give you a swathe of excellent options above "install one fixed theme", and Adaptavist's Theme Builder goes a lot further and lets you re-skin everything (although you do need to put the time and effort into doing the building.  And yes, that was a shameless plug for my colleagues.  But I think they'd agree that to get the best of TB, you need to invest a lot in it)
• Something for diagrams.  Depends on what you're using Confluence for, but Gliffy, Lucid, Draw.io and Balsamiq are always worth a look.
• Adaptavist's content formatting.  Again, not because I work for them - it's the first thing I add to every Confluence I am asked to look at, and has been since Confluence 2.  It's free for the functions I usually want it for, so I can at least try to claim this isn't advertising, but it really does add a lot of handy formatting options
• Comala workflows, if you want some control over publishing rather than a free-for-all (Although you'd be surprised by how many external customers are happy if you explain that you've got an open collaborative platform and hence the docs in some areas are a bit uncontrolled)
• Scroll... well, any of them, when you want what they offer.  A lot of us don't need pages in different languages, but when we do, try Scroll translations.  Some of us need clever and flexible ways to drop pages out to Word documents - Scroll Office.  Or PDFs - Scroll PDF.  Or version-structured docs - Scroll versions. And so-on.

[Steve Boydon]

It's what Confluence was built for.

I currently use it in a consultancy role at a client site. From a perspective of documentation for technical documentation then (also as an auditor) I can definitely say it is 100% fit for purpose. Just for it's inbuilt history and tracking of updates by people it lends itself to replacing MS Office type documents.

There are a number of key addons/macros I use

Multi-excerpt. - Allows you to re-use text throughout the site. As an example have a page called 'roles and responsibilities' and have different items for each position. Do it once, propagate everywhere
Keywords - Good for acronyms, again write once, re-use everywhere.
Scaffolding - Many macros; but one implements the concept of 'Live templates' In a nutshell if you apply something on one page it is changed everywhere. Used with the Scaffolding data it is a very powerful Confluence addon.

Having used Confluence for about 3 years now, I have tried various ways of presenting company documentation, whether it be policy, process, procedure or technical documentation. If used consistently and by all stakeholders, then in my mind it is a replacement for Word, Excel, Powerpoint, Visio with all of the nuances of maintaining documents and keeping them current. As an auditor, it's a ready made evidence tool.