Confluence Best Practices for Technical Writers
The information provided is relevant to Confluence Data Center.
Technical writing is so much more than just writing. Everything matters, starting with content clarity, structure, strategy, localization, and consistency. In this case, the software you use must meet the requirements of technical writers and their teams.
In this blog post, we talk about Confluence as a single source of truth for technical documentation. Moreover, we share some first-hand tips and tricks to organize your content and simplify formatting.
We gathered insightful answers from more than 20 technical writers in this article and would like to share them with you.
- Some tips to start with when you use Confluence as a documentation site
- Confluence life hacks from technical writers we talked to
- Nice-to-haves from the point of view of our respondents and our solutions of how to make it possible in Confluence
Common sense for newbies
Confluence is a powerful platform where you can create and manage technical documentation. It is designed to simplify the collaboration on documents, store files, and organize information, and it’s more visual than just a file repository.
To get the best out of Confluence, define a list of dos and dont’s for your team to follow to ensure you are on the same page when working with content.
Content accuracy
Make someone responsible for the content in Confluence to ensure it is relevant and searchable; otherwise, your spaces become unvisited with the content no longer used . Failure to find this kind of person can also result in poorly titled content in the wrong place.
Structure
Keep the page layout simple and organized. Use headings, lists, and tables to make the page easy to read and navigate. Use the page tree feature to organize related pages under the same parent page and make it easier for users to find the necessary information.
Pay attention to a consistent look and feel and organize pages in relevant sections with links to other related content or external sources. This way, you will help readers find additional information and resources.
On longer pages, use anchors that readers can click and navigate to particular places on the page.
Use page templates to create consistent and standardized pages. This technique saves you time and effort and provides easy-to-update pages with the same structure, increasing the documentation flexibility.
Formatting
Use meaningful headings and subheadings to help readers scan the content. Technical writers should also use images, diagrams, and illustrations to explain complex concepts.
Formatting makes the content more readable. Using bold, italics, and underlining will help draw attention to important points. Break up long text blocks with lists and tables to make content more digestible.
Additionally, use macros to embed videos, images, and other media into your Confluence pages to engage readers.
Confluence tips and tricks from experienced technical writers
And let’s move on to the tips and tricks that help our respondents create high-quality technical documentation in Confluence in no time.
Labels
Labels categorize your pages, especially when you have a lot of documents across spaces. You can organize content into topics, quickly access the required information, and track the progress of different projects and tasks.
Develop your system of labels and add relevant ones to your Confluence pages.
The Content by Label macro comes in handy in this case. It collects references to existing documents by labels on one page in the form of a list.
When a page has a few labels, the Label field browses pages that contain one of them.
As a life hack to narrow down searches, you can use one label in the Label field and one – as a filter. This approach shows the pages with both macros at once.
Code Block
Technical writers can benefit from using the Code Block macro to display code examples with syntax highlighting. With the help of this macro, you can add code snippets directly to Confluence pages.
It’s useful when you need to provide readers with log files. Just put the log file into a code block to retain its formatting.
The comparison between a log file in the Code Block Macro and without it
Note that the coding part is not automatically updated. So you need to check it or have a planned review.
Confluence Source Editor
Confluence Source Editor is a free tool to dig into the HTML of Confluence pages and fix minor issues that can be hard to find in edit mode. This editor has syntax highlighting, a handy search, and replace function.
So when you turn to code, you can change or delete some obstinate formatting and unify the color of your text. You can use it when you copy information from different sources to Confluence, and your final text in Confluence has different shades of black. With the help of this tool, you can search for RGB and delete unnecessary color codes. Or you can set your brand colors for certain elements of your content that are absent in Confluence.
In Confluence edit mode, sometimes you can’t edit a broken link. The source editor will enable you to oversee the link and either change or edit it.
Moreover, it’s better to use the pageId URL format typing [] instead of the page title format or external links to Confluence pages when working with links. If the page is moved or renamed, the page reference will automatically be shown with the new name or location because it’s not static.
Graphics tools
Another nice Confluence feature is that it supports lightweight graphics tools with intuitive interfaces like Gliffy Diagrams and Lucidchart Diagrams.
Gliffy Diagrams is a tool that allows you to produce effective visual aids such as process and procedural flowcharts, interconnect diagrams, etc. Moreover, you can create visually-appealing graphs, charts, and other graphics, either as standalone apps or within Confluence itself.
With Lucidchart Diagrams connector, you can share diagrams like workflows and collaborate on docs through chat and comment on features. When you need to show documentation readers how different components work together to deliver the desired output and help them understand a product better , diagrams in Confluence come to the rescue.
An example of the Confluence page with the Lucidchart app
Reusing content
Another tip is to reuse content with the help of Confluence macros. Of course, copy-pasting also sometimes works. However, when you use the macros created to help you reuse content, you can be sure that when you update it on the source page, the information will change automatically on the other 53 pages with it.
Check out these three macros that save your time when you want to use any piece of content repeatedly on multiple pages in Confluence:
- To create a section that can be reused on different pages, use the Excerpt macro by adding content within it.
- Another option is to use the Excerpt Include macro to include the contents of an excerpt from another page.
- Alternatively, try the Include Page macro to include the entire content in another page.
Our respondents’ nice-to-haves
We also asked our respondents who work on technical documentation in Confluence to complete the sentence “As a technical writer, I would like to …”. Here are the most popular answers we got.
Talk – Advanced Inline Comments is an app that meets all the above-mentioned requirements and can level up and facilitate the daily routine of technical writers who use Confluence.
Suggestions in Confluence
One of the most popular wishes of our respondents is to have the suggestion mode, like in Google Docs, when you can make edits while proofreading the text to speed up the process of reviewing a document. In this mode, content creators can either accept or decline suggestions.
With Talk – Advanced Inline Comments, you can add suggestions to propose changes to any piece of content both in page view and edit modes. And content creators can accept suggestions without switching to edit mode. Moreover, the changes will be automatically applied in one click without typing anything.
Suggestions refine documentation because reviewers can add their notes to a particular place. This eliminates the risk that the page owner will misunderstand the review and make changes by accepting suggestions.
Comments in edit mode
Another nice-to-have when it comes to working with content in Confluence is asking for clarifications from colleagues while editing documents. In this case, you save time searching a context for adding a comment after saving a huge document.
Talk – Advanced Inline Comments helps users rapidly сomment, ask questions, or add personal notes and insights right in page edit mode, not to forget to check details after saving a document.
This feature also eliminates the risk of forgetting anything that came to mind when reviewing a document in edit mode. Moreover, you can set viewing restrictions to comments if you add some personal notes only for yourself or want only specific users to view your comments.
You can also edit a place where a comment was made without deleting it not to lose a task in a comment for review.
Comments as tasks and to-dos
Some technical writers wish to observe their to-dos from colleagues in one place not to miss their tasks and remember the context for changing a document.
They can take advantage of Talk Report and Talk Archive for these purposes.
Talk Report gathers all tasks set as comments (talks) across different spaces in one place. This features provides you with a bird’s-eye view of all discussions, including the information about who assigned the task, task priority, and task content. You can click any task and jump to the page where you need to make changes.
When page owners resolve native inline comments in Confluence, they can not restore them to refresh the context or check the whole comment thread. The Talk Archive feature allows you to check resolved discussions at any time. With the help of this functionality, you can quickly explain to any stakeholders (customers, management, external reviewers) why certain changes were made. Another use case is double-checking the edits after review. This feature also helps restore removed talk discussions to get back important information if you accidentally deleted them.
Confluence for technical writers: Things to keep in mind
By following these best practices, technical writers can ensure their content is explicit, organized, and easy to navigate.
- Find a person responsible for content accuracy in Confluence.
- Mind the structure of your technical documentation, taking advantage of macros and content elements available in Confluence.
- Check templates for technical documentation suggested by the Confluence team
- Use labels to categorize your content
- Reuse content wisely with the help of excerpts
- Check out third-party tools
- Confluence Source Editor
- Graphics tools
- Talk – Advanced Inline Comments
Feel free to share your tips and tricks about how you level up your work with technical documentation in Confluence in the comments below.
