Keep your content up-to-date and still have time for lunch

It's a scenario nearly every technical writer knows from hard personal experience: you're putting in time, energy, and effort to keep your documentation as up-to-date as possible, but you hear from a customer that one of your docs is horribly outdated. Sure enough, when you take a look, it's there: an old screenshot or set of steps that changed months ago. You thought you'd caught them all, but this one somehow slipped through the cracks.

Some writers try to tackle this through meticulous content audits tied to their release or calendar cycles. That solves the problem, but it is time-consuming and tedious.

Here's an adaptable process I've refined over the years to keep my documentation up-to-date with less work. The key? Leverage metadata that tells you which real-world components your documentation discusses, and then run reports to create update lists when those elements are updated.

How NOT to solve this problem

First, a quick warning.

I've seen lots of folks try to solve this problem through organization or hierarchy: putting everything related to a particular function or feature or policy or procedure or department in the same category or subcategory in their site layout.

If your product or service is totally compartmentalized and you can do this, more power to you. But you can spend hours, days, weeks, and even months trying to find a hierarchy that will do it. Inevitably, there are things that don't fit well or the product/service changes in a few months and you have to begin again.

So, step one: don't confuse the information architecture you're presenting to an end-user with the taxonomy or metadata you need to identify things that need updating.

They can--and should--be independent things. Knowledge bases should be structured so that even a total newbie can find what they need; authorial grouping of content for logical updates is often structured in totally different ways. They serve different purposes. If you try to make them both do the same job, either your end-users will struggle to find information, or you will.

Know WHEN you need to update

Staying on top of an ever-shifting body of knowledge can be hard. Even if you don't have the option to make any kind of workflow or tool changes, you can still make life a lot easier simply by figuring out when you need to make updates.

So, ask yourself: what events or changes will require us to update documentation?

For customer-facing documentation, this might include things like:

• New product or course offerings
• Updates to functionality in your product or app
• Updates to regulations impacting your industry
• Updates to workflows or points of contact
• Updates to user interface in your product or app (i.e. entire site reframe or rebrand; tech stack changes; updating layouts to improve usability; etc.)

For internal support documentation, this might include things like:

• Updates to products or applications that your team uses (software versions, even things like VPN login processes, etc.)
• Updates to your hardware or infrastructure (everything from network printers to shared network drives)
• Updates to your company's HR policies and procedures
• Changes to your company's internal organizational structure
• Updates to regulations impacting your industry

Make a list (checking it twice is optional)

Don't just think about these events. Make an actual list.

In fact, make a more detailed list. Ask yourself a second question: What elements of my documentation will be impacted by those events?

Use that question to add detail to each triggering event, so that your list includes the scope of changes each triggering event might impact.

For example, one entry might look like:

Triggering Event: Internal company re-org

Impacted Elements:

• The names of each business unit
• Their business unit head or VP
• A list of key positions or points of contact
• Any org charts or other diagrams in your knowledge base
• Policies or procedures that department is responsible for
• All docs relating to that department
• Content tags or knowledge base organization (depending on current layout)

Format this info whatever way makes sense for you. I've seen decision trees, flow charts, Excel spreadsheets, scribbled lists on whiteboards, a saved to-do checklist or board, and an internal-only knowledge base article documenting it.

I prefer a clear checklist for the event, so it's easy for anyone to walk through the list, mark off what does and doesn't need updating, and assign specific doc update tasks.

But the idea here is that when you hear that a triggering event has happened, you'll know which elements of your documentation you might need to review and update, such as the file for that org chart, or a snippet that provides a product or department name.

Once you've made this list, keep it part of your content workflows so that it's being used and updated. One advantage of having this as an explicit document is that you can then share it with other teams and departments so that they, in turn, know when they need to let you know that they've released a bug fix or launched a new marketing campaign.

Know WHICH documentation you need to update using metadata...

With that list of triggering events in hand, you can then audit your documentation to add metadata relevant to those events so you know which documents specifically need updating.

Metadata exists for a reason: it's information about your docs. Review what your content authoring tools offer you in terms of metadata and use it to your advantage. Evaluate if the tool you're using provides you with a quick way to run reports or lists of your content filtered by that metadata.

What you're looking for is a metadata field (or fields) that will allow you to link your content to the triggering events you identified, so you can clearly say: if [real world condition x ] happens, this piece of content needs to be updated. The specifics of how you'll structure this depend on what kinds of knowledge you're capturing.

This metadata field should be something you can easily get at through queries, filters, or exports. So, for example, if your HR policy changes, and you've stored hr-policy as a piece of metadata, you should be able to pull a list of all content with the hr-policy metadata.

...and workflow/process

Once you identify metadata fields that you can leverage, make populating and updating those fields part of every content creation/publication/update process you have. 

Trust me--once you or your writers see how useful they are and how much time they can save, you'll all probably volunteer to populate those fields!

A real-life example

Let me walk you through how I use this process. Since I write support documentation for KnowledgeOwl, I'll use that as an example. (So meta.)

My triggering event + impacted elements

We are a SaaS company and we have a single product, so basically there are two events that should automatically trigger content updates: bug fixes and software releases. Typically the most complicated triggering event we have is when we update an existing feature, since this means tracking down existing documentation on that feature, rather than writing new from scratch. So:

Triggering Event: Update to existing feature

Impacted Elements

• Articles/categories referencing that feature in passing
• Articles/categories dedicated to that feature
• Screenshots showing step-by-step or feature overview
• Depending on the feature, our main website and our Getting Started guide might also be impacted
• Knowledge base organization, potentially

So, if we release an update to our Subscriptions feature, I know that I need to update text and screenshots in articles and categories, and I may need to review higher-level content and even organization, depending on the nature of the update.

My metadata

But, which articles specifically will I need to update? That's where my metadata comes in!

KnowledgeOwl is my authoring tool, and it has a metadata field called tags. I can add as many tags to an article or category as I need. These tags can be used as filters in our Manage reporting, which is an efficient way to do content audits. So this field seems to give me the flexibility and the reporting I need. (Other tools have different metadata constructs--hopefully whatever you're using has something similar.)

Many people can use their triggering event list itself as metadata. But for a software company like us, basically every piece of content deals with a software feature, so if I just added a tag for "software-feature-update", it would be meaningless.

Instead, we have a tag for each screen in our application. We add that tag to every article or category that includes screenshots or textual reference to that screen. So, for subscriptions, the metadata referenced here is for the Subscriptions Settings page (int: ref-settings-subscriptions). This way, if we make changes to the layout or functionality of this page, I know every page which will need updating.

Metadata setup

Once upon a time, we completed a massive documentation audit, where we reviewed every article in our knowledge base and added tags identifying every page in our app that it referenced. (And if you're shuddering, yes, it is an investment of time and energy. But it's totally worth it!) Now, as we create new and update existing content, we make sure that those content tags are updated. Here, for example, is the tag section of one of our articles:

Sample Tags field in a KnowledgeOwl article

I can tell by looking at this Tags field that this references three pages in the application:

• The Edit Snippet screen (int: ref-edit-snippet)
• The Snippet Library (int: ref-library-snippets)
• The Style > Settings, Custom HTML > Article screen (int: ref-html-article)

(It's also been flagged as needing updated screenshots...because we're still cleaning up things found during the audit!)

The beauty of this setup is that any time we make a change--be it the smallest bug fix or a full new feature--I'm not guessing which pages need updating. I can go to Manage Articles and, with a couple clicks of my mouse, run a filter that will give me a complete list of every article or category that needs updating.

Say, for example, that we updated the Snippet Library interface. Back in the pre-audit days, I most likely would have just searched for "snippet" and then manually reviewed every article that the search turned up.

Now, if we made the change, I could easily go to Manage Articles and find my list:

Instead of spending hours scouring your knowledge base for screenshots or references to the things that have changed, you add one small additional metadata step into your documentation process. Then you can simply run a query, filter, or report and have an immediate list to work through.

More time writing, less time looking.