Making the Convoluted Clear: Strategies for Documentation

Writing good documentation is challenging. You have to take something complex and explain it in a way that’s crystal clear.  And before you worry about getting the content right, you have to figure out the logistics - where to stage your documentation updates, how to get them approved by your PM, and how to ensure that they are ready at the same time as your releases.  This article will explore strategies for doing all of that in Confluence - with a little help from the Atlassian Marketplace.

Where to Draft Documentation Updates

One of the first decisions you’ll have to make is where you’re going to draft documentation updates and how you’re going to make the updated information available to reviewers. Options may include:

• On a private page in your public documentation space
• In a separate “draft” space that mirrors your public documentation space
• On a page in separate space that is created for the purpose of drafting documentation updates

Regardless of which option you choose, you’ll need a way to manage communications between the Product Manager, the Writer and the Reviewer (who may or may not be the Product Manager).

This may take the form of a change log, which includes links to the new content, the status of the update and notes between the Writer and Reviewer:

‍

‍

Alternatively, you can create a Jira issue for each page that needs to be updated. The issue links to the Confluence page, and makes it easy to identify the current status. If the draft page is eventually going to become a page in your public documentation, then using a Jira issue for tracking has the extra advantage of providing a place for commenting, without worrying that those comments will become public. There’s a Content Management Workflow (under the Marketing templates) in Jira Work Management that works well if your managing your documentation in Jira.

‍

Ready on Time

Another challenge is timing. Ideally, your completed documentation updates would be pushed out at the exact same time as your software releases. But a few things have to align in order for that to happen. To be able to take screenshots and ensure that they are referring to elements in the UI correctly, the technical writer needs to have access to an instance where the upcoming release has already been deployed.  If the writer is working on drafting documentation while the new feature(s) is being tested, make sure there is mechanism in place to keep the writer informed of any changes made as a result of the testing.

If your documentation is already pretty dense, and the upcoming release impacts multiple pages, copy and paste may not be a realistic option for getting the draft pages into the public documentation. If there are a lot of pages that you want to publish quickly, then look for a Marketplace app that lets you instantly publish from a draft space to a public space in a few clicks. Scroll Viewport and Comala Publishing are good options to consider.

How to Write Great Documentation

Now that the logistics are taken care of, it’s time to think about the content itself. Documentation should be both concise and thorough. Using a consistent style will also help users find and understand the information. Therefore it’s good to set standards for page layout, formatting and word choice, formatting images.

Page Layout and Design

Using a consistent layout on all of your pages will help users quickly find what they’re looking for. Include a consistently-placed table of contents and links to child pages for easy navigation. Those are just two of the many macros that you can use to make your pages more useable. This page from Atlassian has a nice overview.

Formatting and Word Choice

Clarity is the most important responsibility – and biggest challenge – when writing documentation.  It should be the guiding principle when deciding what words and formatting to use. If you’re writing documentation for a Jira app, then it makes sense to adopt the wording Jira uses (for example, “edit” rather than “modify”). You’ll also want to use some kind of signal (such as bold text) to let the reader know when you’re referencing the UI. Statuses and colored panels can be used to call attention to critical information.

‍

Images and Media

Including images is helpful to visual learners and also makes your documentation more attractive. Big blocks of text can be intimidating.  Images should be cropped so they draw attention to the highlighted feature, but should still be large enough to provide context for where to find that feature on the screen. Standardize the shapes and colors you use for annotating screenshots.

If you feel limited by the way images are handled in the new Confluence editor, or if you’d just like more options, then look around the Marketplace. You’ll find apps for image maps, sliders, diagrams, etc. I've been using Smart Images lately.

Some users will gloss over text and glean the information they need from your screenshots. Others will follow written instructions and pay no attention to the images. Try to include sufficient information for both. If you can, add in some videos as well. Iorad makes it simple to create video tutorials that can be embedded in your Confluence documentation pages.

Keeping Documentation Up to Date

Changes to your software aren’t the only things that will trigger documentation updates. For those us who build apps for Jira, changes Atlassian makes can trigger a lot of revisions. (Please, no more name changes!) More importantly, your documentation should be driven by your customers. Use page analytics to find out what your customers are looking for, then move that page(s) to the top level of your navigation.    A well-written page will be completely useless if users can’t find it.  

Technical writers should also work closely with support teams. Ask Service Agents what the most common customer queries are, and create a label in your JSM project that can be used to flag requests that should trigger documentation revisions.

In the end, creating great documentation is like creating great software. It’s an iterative process that requires a bit of trial and error, frequent updates, and feedback from users.

‍