Tools and strategies for keeping documentation up to date

If you as me to rank the tasks that are under my purview as documentation coordinator in order of how much I like doing them, ensuring documentation reflects software changes is pretty darn low on my list.

I've found a number of strategies and tools that help me to stay sane when it comes to changes in the software that I document, which I will cover below, but I wrote this post as much to share what I do as to learn others are doing.

Many Changes. Much Updating.

The SurveyGizmo application changes quite a bit. These changes usually happen for good reason. For instance, we conduct weekly user tests to evaluate the usability of various areas of our application. Many small but awesome changes come about as a result of user testing.

We also do something called app-sanding, a really cool concept for improving users' experiences that one of my colleagues learned about from a Wistia employee at UserConf (now Elevate Summit).

To quote Jeff Vincent, the sage who gave the talk:

App Sanding means finding places in our customer’s experience that aren’t quite right.^[1]

The idea being that instead of answering the same question over and over because the application isn't clear, just fix the application!

We really took the app-sanding idea and ran with it. In an average week, we release as many as three app-sand improvements to the application.

So many changes!

Strategies For Staying Sane

When it comes to the software changing, I start with two strategies for keeping my head.

1. Get involved with the development team.
2. Evaluate the impact of each change.

Get Involved With The Development Team

Probably the single best thing that you can do for yourself, your documentation, and your customers is to get involved with the development team. In the context of changes that are being made to the software, you can help to ensure that the changes that are being made to the application make sense.

Here are some things that I do to stay abreast of what the development team is doing:

1. Attend the development team's morning standup.
2. Peruse the kanban board (basically a list of what is being worked on).
3. Review the change before it is released.

Evaluate The Impact of Each Change

Many of the changes that are made to the application are made in the spirit of making tasks easier. So, in theory, they shouldn't require documentation; users should just be able to figure out the changes intuitively. Documenting these changes can be lower in priority.

Other changes that are larger or less-intuitive are more likely to require documentation to assist users, so these can be higher priority.

Tools For Keeping Documentation Up To Date

In writing this post I've realized I don't have a process per se for keeping documents up to date. This isn't necessarily bad, in fact, it's probably a good thing that I am flexible when it comes to handling changes.

When you're documenting an agile product, you must be agile yourself. The fact of the matter is we are continuously changing. In 2015 we released 807 times to our production software. Most of these packages include multiple changes. If I treated documenting all changes with the same process and priority it would consume the majority of my time.

I've found that it is more important to stay focused on the task at hand, rather than dropping everything to document small changes. Instead, I use many tools to help me determine what to update and when to update it.

Development Environment

By staying involved with the development team I am aware of what is changing, how it is changing, and when. Knowing helps me keep my head. Having a development environment where I can load up and interact with changes to the software before they are released helps me get a real idea of the scope of the changes. Often, if the change is small enough I update the one or two documents that are affected using my development environment.

If you don't have a development environment, you must get one. This is one of the most useful tools I have for understanding how significant changes will be for customers and for the documentation.

Release Notes

I often go heads-down to do some big picture stuff or to get a new document completed. I use release notes, automated emails sent by the development team, to stay abreast of any changes to the software that might have been released while I was busy doing other things. I commonly leave this task for the last hour of the day when my brain is too fried to do much else. My process is to simply read each change and look for what changed in the application and update documents accordingly. Obviously, these are pretty small changes that weren't big enough to already have my attention.

Traffic

Some documents get more traffic than others. I use this to my advantage. If the upcoming change to the software will affect documents that are not highly trafficked I often leave these changes for those last-hour-of-my-day, release-note-review sessions.

Knowing What To Update

Knowing exactly which articles are affected is the hardest part of the process. I rely almost entirely on my memory. I know my documentation pretty well so I do a pretty good job of thinking of documents that are affected.

I also have an excellent search engine that pretty reliably returns documents that slip through the cracks in my memory.

Tags

Beyond just testing my memory, I use KnowledgeOwl's tagging feature to tag articles with major areas of the application.

When a change is being made that does merit taking the time to update all documentation that is affected by the change, I can simply create a filter to view all articles with a certain tag. Boom! I have a to-do list!

Out-Of-Date Filter

KnowledgeOwl also has a handy out-of-date filter that shows you articles that have not been updated in 6 months (you can create a custom filter if 6 months is too short or too long).

I LOVE this tool for catching changes that slipped past me. As with release notes, if I have some downtime at the end of the day I fill it up with reviewing articles that are 6 months or older.

Just-In-Time

Finally, I have a workflow in place that allows support heroes to very easily notify me when an article needs to be updated. Learn more in my previous post A Practical Guide to Agile Documentation.

What Are Your Strategies And Tools?

As I said above, I wrote this post as much to share what I do as to learn others are doing. What tools are you using, how do you prioritize, are there things we can automate? I would love to hear from you!