Best practices

Owned by Dave Dee
Last updated: Mar 30, 2023
5 min read
1 Writing guides | 2 Editorial workflow | 2.1 Searching content | 2.2 Reducing email notifications

This page includes best practices based on working with engineers, product owners, testers, and other Confluence users. Some best practices are directly associated with default platform features, while others are more process oriented. A single page is used for all best practices instead of a collection of child pages because the best practices are not associated with actions and statuses and a parent page is not needed to collect and display this summary information.

Writing guides

Every organization should adopt one of more writing style guides based on the team, project, company tone, and other factors. Many established guides are available and their guidelines should be adopted (or rejected) as needed.

For a technical audience the following guides are available free of charge from the tech community.

For a nontechnical audience the following guides are available with a subscription.

When a guide is adopted it might be useful to include a summary of the top guidelines to help writers focus on what’s most important. The following summary is from Welcome - Microsoft Writing Style Guide.

Rule

Description

Rule

Description

1

Use simple words, concise sentences

Make every word count. Concise, clear sentences save space, are easy to understand, and facilitate scanning.

  • Use simple words with precise meanings, and remove words that don’t add substance.

  • Punctuating a sentence with more than a few commas and end punctuation usually indicates a complex sentence. Consider rewriting it or breaking it into multiple sentences.

2

Use second person

In second person, you write as though you're speaking to the reader. The second person often uses the personal pronoun you or your, but sometimes the word you is implied. It supports a friendly, human tone and helps avoid passive voice by focusing the discussion on the reader. Omit you can whenever the sentence works without it.

3

Use active voice

Voice is either active or passive. Keep it active whenever you can.

  • In active voice, the subject of the sentence performs the action. For example, ”The dog chases the ball.”

  • In passive voice, the subject is the receiver of the action. For example, “The ball is being chased by the dog.”

4

Use sentence-style capitalization

Use sentence-style capitalization in most titles and headings: capitalize the first word and lowercase the rest.

  • Titles of blog posts, documentation articles, and press releases use sentence-style capitalization.

  • Proper nouns such as brand, product, and service names are always capitalized.

5

Make content scannable

Organize text into discrete components to support scanning. For example, replace complex sentences and paragraphs with lists and tables.

  • Lists are a great way to present complex text in a way that's easy to scan. A list should have at least two items but no more than seven items. Make all the items in a list consistent in structure. For example, each item should be a noun or a phrase that starts with a verb.

  • Tables make complex information easier to understand by presenting it in a clear structure. In a table, data is arranged into two or more rows (plus a header row) and two or more columns.

6

Use numbers consistently

Be consistent in your use of numbers by following these guidelines:

  • When you write about numbers used in examples or UI, duplicate them exactly as they appear in the UI.

  • In body text, spell out whole numbers from zero through nine, and use numerals for 10 or greater.

  • Don't start a sentence with a numeral. Add a modifier before the number, or spell the number out.

Editorial workflow

Additionally, an editorial workflow should be established with at least one editor identified to enforce the guidelines - especially for external-facing documents. A typical editorial workflow in Confluence includes the basic steps described below.

Step

Description

Step

Description

1

Write

Create an initial version of the document.

  1. Include keywords in the document title and body to help improve search results.

  2. When a new page is created in Confluence, stakeholders may get an email notification and can decide to provide feedback. If you’re not ready for feedback, consider including a “work in progress” banner at the top of the document or in the page title.

  3. The document owner (who may not be the document creator) is responsible for managing the editorial workflow and keeping the document up to date.

2

Review

Get feedback from key stakeholders.

  1. Select reviewers. The number and skill set of your reviewers depends on the document. Generally, you should perform a copy edit at least. You might also need a technical review from an engineer or a business review from a product owner.

  2. Create comments. In Confluence, you can create both page and inline comments.

  3. Update the document. The document owner should quickly address comments and edit the document as needed. This will help keep stakeholders engaged and allow you to efficiently complete the document.

3

Approve (optional)

An approval is the final review.

  1. You may need an approval from a SME, a product owner, or a Legal team member.

  2. Before seeking final approval make sure all other stakeholders have provided feedback.

4

Lock (optional)

Prevent user from editing the page.

  1. When a document is complete, you can prevent (or minimize) unwanted changes by restricting page permissions.

  2. Choose restrictions so that anyone can view the page or only specific people can view it. Note that site admins and space admins can view and change the restrictions.

Searching content

Confluence does not always display search results in the order you expect. The main factors that effect search ranking are:

  1. The content type of the matching item including pages, blog posts, and attachments.

  2. The field type in which the matching term was found including title, body content, and labels.

  3. The recency of the matching item based on when it was created or last modified.

For more information refer to​https://confluence.atlassian.com/doc/ranking-of-search-results-1188406620.html. Note that this article applies to the latest installed version of Confluence and may not completely apply to the cloud version.

To increase the effectiveness of your search results, follow these steps:

Reducing email notifications

When there’s a lot of activity in Confluence, you can be overwhelmed with email notifications. You cannot eliminate all email notifications. For example, you cannot eliminate notifications when @mentioned. However, there are two ways you can reduce email notifications.

  • Stop watching pages or a space - You can watch pages or entire spaces and you'll receive email notifications whenever the watched content is added to, edited, or deleted. To stop watchings pages or a space, refer to Watch pages, spaces, and blogs.

  • Modify your email settings - You get email notifications when you “watch” pages and spaces, and Confluence will then send you a notification whenever anyone adds or updates content on that page or space. To reduce email notifications, refer to Subscribe to email notifications.