Best Practices for Documentation in Confluence

Effective documentation is crucial for maintaining clarity and ensuring seamless collaboration across teams. Confluence, a popular collaboration tool, enables organizations to manage and share information efficiently. By adhering to best practices in documentation, teams can enhance communication, reduce redundancy, and ensure that critical information is easily accessible. This guide outlines essential strategies for optimizing your documentation process in Confluence.

Before writing

1. Audience and Purpose: Define who will read the document, under what circumstances, and why you want them to read it.
2. Document Plan: Draft an outline and identify key terms. Search these terms within Confluence to understand existing content and avoid duplication.

Using the page properties macro

• At the end of each document, insert the Page Properties macro with a two-column table for key details.

• Include precise answers to the essential questions in the first few rows.
• Use Action Item and Date macros to highlight overdue updates in red.
• Tag regularly updated documents with "review-list" for aggregation on the Review List page.

Page structure

• Avoid mixing different types of information or targeting diverse audiences within one document. Create separate pages as needed.
• If a document contains several logical sections, each with its own value, it's better to split them into multiple pages.
• When pages share the same goal, audience, and context, they can be combined within a parent page using the Include Page macro. This maintains a modular text structure and displays section titles in the navigation menu.
• If the same information appears in multiple documents, there might be an issue with their structure. In rare cases where duplication is unavoidable, decide on a primary source document and use the Excerpt and Excerpt Include macros to insert content into others.
• Using keywords in tags allows for easy compilation of related article links with the List by Label macro.

Visual elements

• Screenshots and Media: Use clear, annotated images where necessary. Ensure media content supports the text and does not overload it.
• Formatting: Utilize headings, bullet points, and tables to break up text and improve readability.

Content integration

• For embedding external content like Google Drive videos, use the Iframe macro.
• Utilize the Miro and Figma plugins for Confluence to embed respective boards or designs.

Collaboration and feedback

• Incorporate feedback: Actively seek input from colleagues to refine content. An editor’s review can enhance clarity and correctness.
• Track changes: Use Confluence's version history to manage edits and keep a record of a document's evolution.

Continuous improvement

• Regular updates: Schedule periodic reviews to keep documentation current. Assign responsibilities for updates to specific team members.
• Feedback mechanism: Implement a system for users to provide feedback on documentation to identify areas for improvement.

Writing style

• Choose verbs over nominalizations for clarity.
• Write in the active voice and simple sentences to enhance readability.
• Avoid subordinate and participial constructions.
• Use reference style guides such as Google Documentation Style Guide.

Final recommendations

• Always specify a person's role when mentioning them.
• Disable email notifications for minor updates.

These guidelines aim to optimize and standardize documentation practices in Confluence to enhance clarity and usability for project management teams.