Confluence for Technical Writing? Well maybe!

[#1]

I'm a Technical Writer by trade. Documentation is my business, and the tools used to create it are my bread and butter. I've used everything from text editors and word processor apps right the way through to headless CMS packages in the cloud. It didn't matter if they used WYSIWYG editors, markdown, HTML, XML, or DITA. I've seen and used them all to fulfil my craft. Except one!

Confluence had largely remained on the periphery of my radar throughout my career. Sometimes it was there, but there were other tools available. It was a case of use it if you want. Without any formal buy-in, no one did.

I understand the draw of familiarity when choosing a tool. You know how to use it, so why waste time researching if there is something else out there that can do the same job better or cheaper. Us techies frequently fall into that trap when choosing a tool to complete a task, but that is the wrong approach. It is better to list your requirements first, and match those to the products that can meet them. Never do that in reverse unless you want to learn the hard way.

In my line of work, Confluence has a slightly bad reputation. We've been known to turn our noses up at its lack of functionality, but starting a new gig at the start of the year made me look at it close up for the first time. I manage a team of 11 spread across three sites and countries. Our external documentation is authored in an external app, but there was a need for internal documentation as well. Lots of it.

It was time to have a long, hard look at Confluence. How did it match up? Here's my summary:

• Comparing Confluence to an enterprise CMS is pretty pointless. They're both engineered with different user bases in mind.
• Confluence may not have all the bells and whistles of your Adobe, Madcap, or Oxygen XML tools, but that doesn't make it any less useful.
• It is a useful tool for quickly adding documentation for an internal audience without the distraction of variables, snippets, and source control.
• If you want to be clever, there's a wealth of macros and plugins available to do wizz bang things techies like.

Confluence has provided us with the ability to develop and update our team policies and procedures, and structure them in a way we can easily find them.

One final tip. If you want to get the best out of Confluence, make someone responsible for the content. Failure to do so will make your space a dumping ground, that will soon become unusable. Whether it is out of date content, or just content in the wrong place or poorly titled, someone needs to have oversight to ensure your content is both accurate, searchable, and useful.

[G subramanyam]

Hi @Colum McAndrew that's quite an engaging read. And I highly appreciate the way the things have unfolded for confluence and for it's usefulness. 

Thank you for joining our "New to confluence" group and your introduction . Would you mine posting your social media handle for sending request.

Happy Friday and weekend.

[Colum McAndrew]

Thank you for that feedback @G subramanyam I'm glad you found it engaging. My Twitter and LinkedIn socials can be found in my profile. 

[Kevin Tuei]

This is quite engaging and insightful @Colum McAndrew There is always that one thing that can make you have a long hard look at that one solution we have been keeping on the side. More often than not, as you have said, you may have a great tool such as Confluence but if you don't have the people then the usefulness of it will not be fully realized. 

[Clark Everson]

This is a really well written article. I've always liked writing and been drawn to Confluence. my grandfather was a technical writer for years so very interesting to see it from that perspective.

[Colum McAndrew]

Thanks for that feedback @Kevin Tuei and @Clark Everson. Ask 100 Technical Writers which CMS they'd recommend, and you'll get 100 different answers. Well at least you would if there were 100 CMSs :-) However ask 100 good Technical Writers which tool they'd recommend, and they answer with lots of questions around your requirements.

Technical writing is so much more than writing, in the same way that driving a car is more than just turning on the ignition. Content structure, accessibility, readability, localization, content reuse, style, consistency, content strategy, SEO, and more all play their part. So the CMS you use must meet whatever requirements you have.

In the same way we have a preference for Apple or Samsung phones, we have fans of specific CMSs. It is important to remember though, that each app / phone is just as good as another if it meets the needs of its user.

[Irina_Bel_Stiltsoft_]

Hi there,

I've recently analyzed best practices for technical writing in Confluence in this article.

You will find some non-trivial tips for creating the docs in Confluence that your team will want to read and share. I hope it will be of help to you.