Confluence Best Practices for Technical Writers
You need a great technical writing tool to sync with product and development teams. That’s where Confluence comes into play. With more people switching to online documentation and collaborative tools like Confluence, technical writers need to understand the best practices that come with using such platforms.
In this blog post, we’ll explore Confluence as a collaborative platform for technical writers. We’ll also discuss the best Confluence practices to help you effectively create and collaborate on technical documentation.
Here you’ll learn about:
Tips for newbies to start their journey with Confluence:
- Content accuracy
- Structure
- Formatting
Tricks and tips for technical writers:
- Labels
- Code block
- Confluence source editor
- Graphic tools
- Reusing Content
- Page templates
- Track page updates
Nice-to-have features:
- Suggestion mode
- Comments in edit mode
- Comments as tasks and to-dos
Insight for Newbies
Confluence is a web-based platform for knowledge sharing and collaboration. It allows teams to work together in an organized and efficient manner, thus making it easier to create and update documents quickly.
One of the vital aspects of using Confluence for technical writers is ensuring the content remains organized, concise, and easy to read. It also enables you to store files and gather information more efficiently to help streamline the workflow.
Moreover, you can create dos and don’ts lists, write detailed instructions for users, and use formatting options. These aspects improve the collaboration of your team for more efficient technical writing.
Content Accuracy
The accuracy of your content is a key factor when it comes to creating a successful technical document. Make one of your team members responsible for the accuracy and consistency of your content. Find someone familiar with the company’s language and use them to help review your content. It ensures that your space is always up-to-date and relevant. Without a responsible person checking everything, your spaces get occupied by outdated information and unnecessary data.
Structure
Create a well-organized and simple page layout. Add headings, checklists, and tablets to make reading easier for readers. Page tree macro is one of the best features in Confluence to enable you to display the entire page structure on one parent page. It will help you define your content’s structure and make navigation easier for your readers.
Moreover, the outlook and design of the page should be attractive and visually appealing. Use visuals, screenshots, and videos to help explain complex concepts. Avoid duplicating content. Instead, link to related pages and ensure all the content is accurate and up-to-date.
Use anchor text for longer pages to help readers navigate the relevant content on the page. Moreover, page templates are also helpful as they streamline processes for your team. They allow you to create consistent pages with a standard structure and help readers to find information. This feature makes the page updating process easier and faster. It also helps to improve documentation flexibility.
Formatting
Formatting is vital when creating technical documents. Add comprehensive headings and subheadings throughout the text. It will not only make the content easier to read but also help readers navigate your pages quickly. Using images, illustrations, and diagrams can also help explain complex topics.
Adding italic, bold, or underlined fonts to highlight certain words can make your content look more attractive. Use bullets and numbering to show the hierarchy between different points.
In addition, adding annotations to explain the content or images can help understand the context of a particular concept. Annotations should be clear and concise.
Instead of adding long text blocks, break them into smaller sections to make it easier for readers to digest. It will also help you avoid making the page look cluttered. Moreover, employ macros to add videos, images, or other media to your page.
Confluence Tips and Tricks from Experienced Technical Writers
Let’s take a look at some tips from experienced technical writers to help you use Confluence more effectively:
Labels
Organize your content for easy retrieval using labels. Labels can help you categorize pages effectively so readers can find relevant information quickly. They provide quick access to content and enable you to track the progress of your projects.
Create a system of labels to keep everything organized. Add relevant labels to each page and use the search bar to find them quickly. Content by label macro is a great tool to create a table of contents based on the labels you used on your page. If a page comprises a few labels, the Label field macro will help you list them and add links to the corresponding pages.
Code Block
When writing technical content, you often need to include code snippets, like excerpts from application logs, sample code, and terminal commands, for readers to understand a concept. The code block macro allows you to add syntax highlighting to your pages. It makes it easier for readers to identify the language and understand the code.
This macro is beneficial when you have to provide log files to your readers. Place log files inside a code block to maintain the format and make them easier to understand. You need to plan a review or check to update the coding part, as it is not automatically updated.
Confluence Source Editor
When you are working on Confluence, the source editor is a great tool that helps you create content quickly. It allows you to fix minor issues by using HTML. It is especially useful for technical writers who have to work on tables, images, charts, etc., that require HTML coding. The syntax highlighting, searching, and replacing functions make the job easier.
This feature enables technical writers to alter or eliminate obstinate formatting issues. With the source editor, technical writers can add rich text snippets like headers, footers, and special characters without using HTML.
These are some of the Confluence best practices for technical writers that can help them create content quickly and efficiently. Using these tools, you can unify the text color of your content. It also helps to save time on formatting the content. With this tool, you can remove unwanted color codes and apply your own style to the content. It also enables you to add unique shades that represent your brand but are unavailable in your source code.
You can’t always edit faulty or broken links with Confluence edit mode. The source editor allows you to search for these links and quickly fix them. In addition, using the page Id URL format typing is a better option than manually typing a link. You’ll get a page reference with its title and location if the page is displaced or renamed.
Graphics Tools
Another commendable Confluence feature is its support for graphic tools, including Lucidchart Diagrams and Gliffy Diagrams. These graphic tools have intuitive features like flowcharts, drawings, and diagrams that help technical writers easily explain complex concepts. The graphical elements also give the content a professional look.
Lucidchart Diagrams Connector enables you to create diagrams and flowcharts with automation. This tool enables you to improve your team’s collaboration by sharing and editing diagrams within Confluence using chat, comments, and shared branches. Your team members can edit the same document while seeing each other’s changes in real-time. It also offers a presentation mode and a version history to keep track of the changes.
Gliffy Diagrams is an ideal tool for creating flowcharts, wireframes, mind maps, and other diagrams. It enables you to create visually appealing diagrams in minutes. After creating the diagram, it can be embedded in the Confluence page quickly. Gliffy also allows you to import from other tools, like Draw.io or Visio.
Reusing Content
Reusing content is another important Confluence best practice for technical writers. It helps you save time by enabling you to use a word, sentence, paragraph, or image as many pages as you want to. You need to create it once and use it repeatedly. This feature is especially useful when you create a series of documents or pages with the same content. Reusing content also allows you to keep a single source of truth, which ensures accuracy and consistency in your content.
Confluence offers three macros that enable you to reuse content:
- Expert macro helps you use a section on multiple pages. Add content to it and use it across various pages without having to create individual content for each page.
- The Excerpt Include macro enables you to include an excerpt From one page into another page.
- Include Page macro allows you to include an entire page on another page. It is an excellent way of displaying the same content on multiple pages without having to copy-paste it.
In addition to using these macros to reuse content from any page, you can create an inclusive library to store content. This library can store text, images, videos, and documents for reuse on any page.
Page Templates
Creating page templates for Confluence helps you quickly create pages with the same layout and structure. Page template is beneficial in a setting where you need to create multiple pages with the same content.
If you are using the same macros and layout, you can create a page template for it. It will save time as you don’t have to insert everything into the page manually. Moreover, you can create as many page templates as you need and use them when needed.
Track Page Updates
While various people are working on a single document in Confluence, you need to keep an eye on the updates. The watch feature in Confluence allows you to keep track of any changes made to a page or document. Whenever you visit a page, blog, or document in Confluence, the watch feature is automatically enabled. You will receive email notifications whenever the content is edited, removed, or added. It is a great way to monitor any changes made by colleagues.
Version history also enables you to track any changes to a page. Whenever your page is edited, Confluence will store a copy of the previous version. It allows you to revert back to a prior version if needed.
The contributors macro allows you to see who is contributing to a page. It provides you with a customizable list of all the contributors to a page. It helps to keep track of the contributors’ activity in Confluence.
Confluence Nice-to-Have Features
We ask our respondents about the features they think are nice to have in Confluence to make technical writing easier.
Talk – Advanced Inline Comments offers you various solutions to improve your experience with Confluence. This app offers several features for technical writers for easy collaboration and better management.
Suggestion Mode
It’s a common wish that many technical writers want to see in Confluence. Like Google Docs, Confluence doesn’t have any feature that provides you suggestions regarding how to improve your content. This feature can significantly speed up the proofreading process.
Talk – Advanced Inline Comments enables you to propose suggestions to any document or page. You need to enable select the content in the document and write the suggestions. The document owner can accept or reject the suggestions and make changes according to your requirements. The accepted suggestion will automatically be applied to the document with a single click.
Suggestions are crucial for any document as they refine the content and make it more precise. This feature can help the document owner improve the content by going through the suggestions of the reviewers.
Comments in Edit Mode
While editing a document, you might need clarification from the team members or need help to remember what you were working on during a certain part of the document. In such cases, adding a comment and asking about the context can be very helpful. It also increases the engagement of the collaborative team members.
Talk – Advanced Inline Comments allows users to add comments while in the edit mode. It is very helpful for technical writers as they can add questions or comments regarding any part of the document without switching away from the edit mode. It saves time and effort while editing a document, as the users can ask for help within the same view.
It’s an amazing feature that enables you to leave a reminder for yourself or any other team member. It also reduces the risk of overlooking anything important while reviewing a document. This feature also allows you to add viewing restrictions to the comments.
Comments as Tasks and To-Dos
Observing to-do’s in any document can be helpful for technical writers. This feature reminds you about the tasks you need to complete. It also helps in setting deadlines for the tasks and tracking them.
You can employ Talk Report and Talk Archive for this purpose.
Talk Report is a feature that allows you to review the comments and tasks associated with your document. It shows all the comments made in chronological order, allowing you to view the progress made by each team member. With this tool, you can keep an eye on your team’s progress and manage the to-do’s efficiently.
Talk Archive enables you to observe resolved discussion threads so that you do not miss out on any important details. It enables stakeholders to learn why certain changes were made. It also allows you to restore deleted discussions if you need to review them.
Things to Keep in Mind While Using Confluence
Following the best practices for technical writers can make their content organized, explicit, and easier to navigate. Here are some tips to make the most out of Confluence:
- Find a responsible person who can ensure content accuracy.
- Use macros and content elements (like tables or lists) in Confluence to format the content.
- The Confluence team offers various templates. Use them to create a consistent design for your technical documentation.
- Add labels to categorize and organize the documents.
- Use the inclusive library to hold the content you want to reuse in one place. Reuse the content wisely.
- Create page templates to be used as a guide for each record.
- Ensure you adhere to security policies and guidelines when sharing documents with other teams.
- Regularly review the content and update it as needed.
- Employ third-party tools, like Talk – Advanced Inline Comments, to make your content more interactive and engaging.
And there you have it, the best tips and practices for technical documentation in Confluence.
