When should technical documentation teams consider a content system migration?

A couple of years ago I spoke with a technical writer at a software company. She had this colorful system for keeping track of her product lines – a set of color-coded sticky notes on the bottom third of her monitor, each product line represented by a note. But each note represented more than just a product line – it also served as a reminder to her of the different versions of content chunks that would reside in different folders on different shared drives, maintained by different people. So she wasn’t disorganized, she was working within the limitations of her documentation system.

The writer in the picture is currently working with the sticky notes that are shown to be covering the bottom third of her monitor. Each sticky note and color represents a different product line. The sticky notes contain information about the different content chunks and the corresponding folders on the shared drives that the writer’s colleagues have updated the content for. The image has stuck with me because it represents how a team can work with the tools that they have even if the tools are no longer ideal for the team as it grows. She is working in a functional but very tiring manner.

The signs aren’t always obvious

Content system pain doesn’t announce itself. The documentation workflow or content system or whatever you want to call it in your organization doesn’t announce that it’s broken. It’s become so normal for people to do documentation in certain ways, that the little bit of extra work or pain that they are putting into it in order to get the job done is just absorbed as part of doing their job. It’s not noticed anymore, until somebody does a study and finds out that it is taking a long time to do documentation. Then they might figure out that it’s because of a little bit of extra friction in the process here.

Some of the most obvious signs of pain in a documentation team:

• Writers spend more time hunting for the right version of a topic than actually writing
• Publishing to multiple formats requires a half-day ritual of manual adjustments every single time
• Onboarding a new writer takes weeks, not because the content is complex, but because the system is
• Translation or localization projects cause widespread panic across the whole team

When 2-3 of these make sense to you then you likely don’t have a skills or process problem – you have a tooling problem. And yes, that’s a different conversation which needs to be held (which can involve coaching) as opposed to asking for more budget to continue as is.

The moment scale breaks everything

Small documentation teams can work with a few files in a shared folder, on a wiki, or in a well-managed Google Drive. A two-person team might be able to make a number of documentation tools work. But as team size grows to about 5-7 people, the number of reuses, and the complexity of those reuses, changes dramatically.

Reuse turns into a disaster area without a content management system. Single sourcing, which sounds so great in theory and almost looks like architecture, turns into a mess of copy & paste decisions that nobody can fully track because nobody actually made the decisions. When a product update affects 40 topics instead of 4, the difference between a solid system and a disaster area is the difference between a productive week and a week of total chaos where everyone is trying to put out a fire while simultaneously adding fuel to the blaze.

I still have those sticky notes in my mind. It’s not that the writer was failing in her job, but rather that the writer’s job had grown to the point where it had a second skeleton that the writer’s tools couldn’t support.

What migration actually involves (and why teams keep postponing it)

No matter how much I explain to people that the pain of the years leading up to the documentation system migration far outweighs the pain of the actual migration, it seems that so many documentation teams are willing to suffer through years of decreasing productivity and increasing frustration in order to avoid what they fear the migration will be. The reputation of migration for documentation systems has been an expensive and highly disruptive project. It has a somewhat threatening connotation, as if to say “We are going to fix this, even if it kills us.”

The true cost is not the migration itself but rather the years of hidden inefficiency that you were unaware of while documenting using a less-than-ideal tool and process until that point in time.

Please be aware that the above is somewhat of a simplistic view of how to migrate to a CCMS. Such a project is a long and arduous one and can be best viewed as a series of decisions. Many teams have gone through a similar transition and it might be worth reading about their journeys, especially from tools like Flare to IXIA CCMS migration (see this blog post for example). Avoid the sales pitches of the vendors as they tend to gloss over the ‘difficult’ bits and instead read around the topic to get a good feel of the types of decisions that one would need to make in such a transition.

Here is a simplified comparison between what a documentation team might look like before a team begins to utilize a CCMS, and what a team might look like after they have fully implemented a CCMS and are utilizing all of its features.

So when is the right time?

The sooner you start documenting the need for better tooling the better. For most teams it is too late once they have recognized the problem, as they are already are too busy creating and shipping the best quality documentation as it is.

Later I went on to describe in detail to how other teams had reached a ceiling, scaled to new heights and realized that something had to change when they hit a new ceiling for their documentation. It is usually a major product update, a team reorganization or even a new localization release that triggers the effort to switch to a CCMS. The needed effort to set up a good set of tools and processes for the documentation is partially already needed for the upcoming product update, so the pain of change is not as huge as one might initially fear. Watch for these opportunities to climb through to new heights quickly.

Watch for these moments to scale your documentation tools with your product(s), writer(s) and documentation. The moments occur more frequently than you think and can be climbed rapidly to take advantage of the overlap in crisis and tooling renewal before the window closes.

What To Ask Your Team Now

This is not the time to be figuring out what system to use. Wait until you’ve done some hard work to figure out what your problems are, and then ask your team “What would we stop doing tomorrow if we could?” The things that you would stop doing are your problems. If half of the people in the room name the same work-around, unprompted, independently, that work-around is your problem. Not a symptom. The answers will tell you more about your actual pain than any vendor demo ever will. If half the room names the same workaround, unprompted, independently, that workaround is your diagnosis. Not a symptom. The diagnosis. Getting there clearly, without flinching at what it reveals, is genuinely the hardest part of the whole process.

The answers to this simple question will give you a lot of insight to the actual problems the team is facing. If half the team mentions the same workaround (e.g. creating printed sticky notes) without being prompted, then that workaround is likely the root cause of the team’s current problems. Finding the root cause clearly and agreeing upon it is the hardest part of the process.

(As an aside, the writer of the sticky notes said she had been using that method for two years prior to realizing she was writing with a system of sticky notes.)