Strategies for Managing 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. (I am not affiliated with any of the apps mentioned in this article.)

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.

 image-20210802-152543.png

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.

CM_WF.png

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.

pills.png

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.

5 comments

Samie Kaufman - Your Gal at Gliffy
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
November 18, 2021

Some great tips in here! I definitely agree with breaking up big blocks of text with bulleted or numbered lists, graphics, tables, and diagrams. You don't want your documentation to fall into TL;DR territory. 

I also like the idea of technical writers partnering with support teams to determine how to prioritize or structure info. I feel like our support team does an awesome job of flagging when documentation is out-of-date.

Sven Schatter _K15t_
Marketplace Partner
Marketplace Partners provide apps and integrations available on the Atlassian Marketplace that extend the power of Atlassian products.
November 19, 2021

Wow @Jennifer Choban, the quality of this article is through the roof! Awesome work!

My team at K15t has compiled an amazing guide called Rock The Docs which I think is a great addition to your article if you want to get even deeper into the topic. Also, thank you so much for mentioning our app Scroll Viewport! :)

Cheers,
Sven

Like # people like this
Aron Gombas _Midori_
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
November 19, 2021

@Jennifer Choban Great work with the article! There is clearly a lot of practical hints here.

I'm not sure if you and the readers know, but the Better Content Archiving app helps to conduct (or fully automates) the periodic maintenance work you outlined in the "Keeping Documentation Up to Date" section.

Matt Reiner [K15t]
Marketplace Partner
Marketplace Partners provide apps and integrations available on the Atlassian Marketplace that extend the power of Atlassian products.
December 21, 2021

@Jennifer Choban so many good points here! Thanks for sharing. I love your note at the end to let users drive your documentation. That's so important! Also, I totally love using Jira Work Management to handle the documentation workflow, especially if you're working with other team members who are managing their workflow there.

Like Sven Schatter _K15t_ likes this
Stavros_Rougas_EasyApps
Marketplace Partner
Marketplace Partners provide apps and integrations available on the Atlassian Marketplace that extend the power of Atlassian products.
October 26, 2023

To add to the valid point about "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."

Small changes can cause a mess for users. I just wrote this on the Atlassian Community about keeping text up to date in bulk.

We focus on building tools to bulk update content in Confluence, we keep learning about pain points. When the pages are public mistakes are a pain for users.

Like Stavros likes this

Comment

Log in or Sign up to comment
TAGS
AUG Leaders

Atlassian Community Events