How to Write Documentation as a Team in Confluence

[#1]

I'm part of the K15t team, and we've been using Confluence for our product documentation for a while now. We’ve heard this question many times: Can you write documentation using proven technical writing methods in Confluence?

That’s a good question, and the answer is a solid “Yes”. Good documentation in Confluence is all about the way you go about it. We’ve found that a good process and techniques are the key to well-formatted and organized documentation.

To share what we’ve learned about writing great documentation as a team in Confluence, we’ve created Rock the Docs: Your Team’s Guide to Documentation in Confluence. The guide contains a wealth of helpful information for your team, but here are a few tips to help you get started:

Topic Creation and Review

To build trust with the users reading your documentation, keep your content consistent. Creating an initial set of templates for your documentation in Confluence will help your team get writing quickly. Depending on the type of template,you might include:

• An Excerpt macro
• A Table of Contents macro
• The beginning of a list or table

For each macro and item you add, use template variables and instructional text to guide writers as they begin. Looking at a blank page is a tough way to start writing, even if you do it all the time. Any instruction you give will enhance your team's workflow.

When you have a first draft of your documentation, share the page with all members of your team who should review it. The speed of sharing and commenting in Confluence is most likely known by everyone here, so we won’t elaborate. Let’s just say, we love how quickly your team can review documentation and share improvements.

Learn more about creating topics and collaboration.

Reuse Your Content or Make it Conditional Like a Pro

As you create documentation, create pieces of content to reuse in multiple places, or maybe even highlight or display certain content for specific users.

1. Create a new space to act as a "library" for the content you want to reuse throughout your documentation.
2. Add pages containing the content you want to reuse to the library space. This could be as simple as a single image or several paragraphs of text.
3. Use an Include Page macro where you want to reuse the content in your documentation and select a page from your library. You can reuse a page in your library as many times as you'd like, and if you ever need to update the content, you'll only need to do it in one place.

There are a few different approaches for displaying different content in Confluence for different users. A simple approach is to put content for different users on separate pages, like "Getting Started for Administrators" and "Getting Started for Developers". Another simple approach is to put all content on the same page and use headings or even the Expand macro to visually separate the content for each user. For more advanced use cases with multiple conditions defining who should see what and when, there are some Confluence apps that can help.

Learn more about content reuse and conditional content.

Track Changes, Manage Languages, and Publish Your Docs

When it comes to writing your documentation collaboratively with your team, the last thing you want is for changes to be made, translated, and published haphazardly. The key is good process and tools for keeping your team working well together.

Versioning

As you create new versions of your product, you'll need to also create new versions of your documentation. What's tricky is that you'll need to keep version 1.0 of your documentation around for people using that version of the product and also work on version 2.0 at the same time. There are several ways to accomplish this:

• Create a copy of the space with the most recent version of your documentation and use the new space to write the documentation for the next version
• Create all documentation in one space but hide the pages that aren't ready yet using page restrictions
• Use a Confluence app to create all documentation in one space and designate the version in which changes should be included

Languages

If your team documents in multiple languages, you'll need a good process for ensuring all languages get updated when documentation is changed. You can manage this with a strict manual process your team agrees to follow, or use a Confluence app to automate the translation workflow. You can write multiple languages in a few different ways:

• Write each language on a separate page, like "Introduction" and "Einleitung". Your page tree can help separate different languages
• Write each language in its own space, like "Documentation, English" and "Documentation, German"
• Use a Confluence app to manage multiple languages in a single space and bring in content from an external translation system

Publishing

When it comes to distributing documentation to your users, there are multiple options for publishing:

• Share your documentation on the web by exporting the space as HTML pages or enabling anonymous access to the space. You can also use Confluence apps to export your documentation as an HTML site or theme an anonymous space as a help site
• Distribute your documentation as documents by exporting your space as a simple Word or PDF file or use Confluence apps to create a customized Word of PDF file using custom templates
• Provide context sensitive help in your product using Confluence apps to link directly to your help site or export your documentation to add help directly in the UI

Learn more about versioning, multiple languages, and publishing.

Writing in an Agile Process

We recommend every team use an agile process for product development and documentation at the same time. Agile ensures your team can ship both as soon as they're ready. Agile processes reduce the amount of needless internal documentation your team creates and help deliver great documentation to your users. For example: the epic, user stories, and acceptance criteria created during an agile process serve as a map for the documentation your team should write.

This is just one example of how agile processes make documentation great.

Learn more about using an agile documentation process.

Learn More and Help Improve the Guide

We go deeper into each of these topics in the guide, so please have a look. Give us feedback on what questions we haven’t answered and tell us how it can be more helpful. This guide will be a longstanding resource for the Confluence community, and we love collaboration, so we’re excited to hear from you.

Learn more at: Rock the Docs: Your Team's Guide to Documentation in Confluence