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:
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:
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.
As you create documentation, create pieces of content to reuse in multiple places, or maybe even highlight or display certain content for specific users.
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.
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.
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:
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:
When it comes to distributing documentation to your users, there are multiple options for publishing:
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.
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.
Matt Reiner [K15t]
Last week Megan Cook, Head of Jira Software and Mahreen Khan, PhD, Organizational Psychology hosted an “ask me anything” session focused on the psychology of agile teams. We received 22 questions, 16...
Connect with like-minded Atlassian users at free events near you!Find an event
Connect with like-minded Atlassian users at free events near you!
Unfortunately there are no Community Events near you at the moment.Host an event
You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events