Confluence 5.7: Inline Comments vs. Page Comments

8 min read /

Confluence 5.7 was the first release to boast inline comment functionality. The entire Confluence user community – including ourselves here at K15t Software – instantly fell in love with this new way to close the content feedback loop.

But can inline comments be used for questions and feedback on public documentation sites? Or are comment threads below pages still the best way to interact? This key issue was discussed on the Atlassian Confluence documentation site.

Here’s a wrap-up of that discussion – plus some best practices for using inline comments or choosing (threaded) page comments in Confluence.

Inline Comments in Confluence

The inline comments functionality allows users to review Confluence pages line by line and add comments on selected words, phrases, or entire paragraphs. Once you’ve added your feedback, you can resolve comments simply by clicking ‘Resolve’. This fun, one-click solution allows users to add their comments while viewing the relevant section of text – eliminating the need to scroll down to the comments section.

Inline comments provide a real boost to productivity for (small) teams who need to discuss a documentation page while it’s under construction.

Feedback Loop on Public Documentation Sites

If you browse any public-facing Confluence pages, you’ll notice that inline comments are still disabled, even though the site runs with Confluence 5.7+. Why is this?

  • New visitors to the pages could be confused if help content contains extensive orange mark-up.
  • Visible inline comments can significantly impact readability. 
  • Confluence’s inline commenting feature was not designed for use by large audiences. It is most effective for smaller groups during the drafting phase. These groups typically consist of one or two experts, plus a technical editor in most cases.

As a rule, the ‘old-fashioned’ comments system remains the best way to keep pages clutter-free and avoid confusing casual readers.

Threaded comments, in a separate section below the page content, provide a more structured way for readers to interact and provide feedback. And technical writers – such as the Atlassian team â€“ benefit from this concise way of referring and responding to questions.

Best Practices for Displaying Comments

Inline comments are suitable for small groups of collaborators during the content drafting phase, and can be used to gain feedback on specific sections of text before the content is published.

If you want to use Confluence to provide public-facing content, we recommend that you stick to threaded page comments (and disable inline comments). This is particularly advisable if you know your readers are inexperienced Confluence users who might prefer to leave their comments and feedback below the page.

How to Show Inline Comments in the Confluence Editor 

Being unable to see inline comments in the edit mode of Confluence causes efficiency issues for some teams. This costs a lot of time, especially when writing a lot of text collaboratively, e.g. technical documentation. Most users work around this problem by placing two windows side-by-side. This frustrating approach might work for some, but the functionality is still missing. 

So K15t developed an app called Inline Comments in the Editor. When the app is toggled on, it enables Confluence to show inline comments in edit mode in the same way you view and interact with them in view mode. You can directly edit and resolve those comments without opening a new window. 

Want to see inline comments in the Confluence editor?
Try it free

Show Inline Comments in the Confluence Editor

How to Disable Inline Comments in Confluence

At the moment, inline comments can only be deactivated globally (i.e. for the whole Confluence instance) by disabling the Confluence Inline Comments system add-on:

  1. As a Confluence administrator, visit the Manage apps administration page.
  2. From the filter drop-down menu, select System.
  3. In the list of system plug-ins, select Confluence Inline Comments.
  4. Click Disable to deactivate the inline comments feature globally.

Please note: Any existing inline or pinned comments will no longer be visible. However, page comments will still be available, provided that your users have sufficient permissions to view or add comments.

Best of Both Worlds: Publishing Content with Scroll Versions

Do you want to discuss your content internally, and then publish it to a public Confluence space? If so, why not try Scroll Versions? This Scroll content management app allows you to publish content from one space to a new or existing space. And if you install Scroll Remote Publishing Endpoint, you’ll be able to publish to a remote Confluence system, too.

By deploying these apps, you could use inline comments on your content development platform, and then publish or update released content to the public Confluence system, where the inline comments feature is disabled.

What’s Next?

Now you know the potential uses of inline comments, let’s consider what could happen in the future. A first step could be to make inline comments less intrusive for the reader. And in some cases, admins would benefit from being able to clear all inline comments with a single click.

If we could have just one wish, we would ask to have space-level permissions for adding or deleting inline comments. It would also be a great help if only users with ‘Create’ or ‘Edit’ permissions could actually see inline comments.

However, the inline comments feature is sure to keep evolving in the future – and Atlassian has already made real progress towards creating a user-friendly feedback loop for Confluence content. 

What do you think about Confluence’s feedback loop? What approaches do you use to involve editors, experts and readers in your content lifecycle?

Please leave a comment below, or drop us an email at info@k15t.com.

Did you enjoy this article? Get a monthly digest sent to your inbox by subscribing to our newsletter.
Subscribe