Auditing the Gaps: A content analysis approach for inherited docs

There’s a predictable arc to inheriting someone else’s documentation. At first, before you really know the product, the problems look manageable — inconsistent terminology, sections that could be clearer, some structural cleanup. You make a list. You feel like you have a handle on it.

Then it becomes yours. The light bulb clicks on, and the list you made starts to look like the surface of something much bigger. I can’t think of a single set of inherited docs that weren’t in some version of this mess — and I’ve walked into it more than once. It’s not a you problem. It’s a field-wide experience, and the writers who’ve been around long enough to compare notes all have the same story.

Before you can fix any of it, you have to find all of it. That requires analysis, not instinct, and it takes longer than anyone outside the field expects.

Not all debt looks the same

Not all documentation debt looks the same, and treating it like it does is where a lot of writers get stuck.

The content that exists — outdated, inconsistent, poorly explained — is actually the easier problem. You can benchmark it. You can put it in front of the people who built it and ask questions. There’s something there to react to.

Missing content is harder, because there’s usually a reason it’s missing. If it was never documented, chances are it was never emphasized internally either. Product didn’t flag it. Engineering didn’t ask for it. It just quietly fell through. And that creates a specific problem: you can’t point to a gap the way you can point to a broken link. There’s nothing there to flag. You have to know something is absent to notice the absence.

Start with the user, not the content

Before you touch the docs, go to the people closest to the customer experience. Not product. Not engineering. The support engineers, solutions architects, forward-deployed engineers — the people who field questions, who watch users get stuck, who have heard the same gaps complained about dozens of times. UX researchers, if you have them, can be surprisingly useful here too.

These conversations are your first gap inventory, and they come pre-ranked. The questions that come up most often are the ones with the highest impact. Whatever keeps showing up in support queues or customer calls is almost certainly something the docs aren’t answering, and you didn’t have to build a spreadsheet to find it.

Build the map

There’s no single right way to build the map, and the approach that makes sense depends on the scale of what you’re dealing with.

For a smaller doc set, rough notes can be enough. You’re looking for threads — recurring topics, structural patterns, where things cluster and where they don’t. You don’t need a formal artifact to reason about a manageable set of content.

For something larger, you need more structure. I’ve pulled in stakeholders from outside the docs team to go through content together and classify it. The goal wasn’t just inventory — it was shared understanding of what existed and what it was supposed to be doing.

In one case, I took a different approach entirely. Rather than cataloging what was there first, I built a mental map of how the content should flow: Overview and concepts, User guide, SDK, API. Then I used AI to help identify all the content that fit that structure and did a lift and shift. Once everything was organized, the gaps became visible on their own. Broken flows in the information. Topics that didn’t fit anywhere. Content that existed but had no logical home.

In another case, the docs were too large and the workload too heavy for a full inventory upfront. Instead, the customer journey became the map. Through interviews with solutions architects, I built an understanding of how customers actually moved through the product. Then I worked topic by topic: before writing anything new, I’d use AI to help surface everything that already existed on that topic, do a quick audit of just that slice, then pull it all together before moving to the next. It made an overwhelming problem manageable, and nothing got missed.

The method changes. The goal doesn’t: get it out of your head and into a shape you can reason about.

Find the holes

Some gaps announce themselves. When you step back and look at the map, there are obvious holes — entire features with no coverage, content so out of date it’s actively misleading, topics that moved but left no forwarding address. These are the glaring ones, and they’re usually the first things that surface.

The subtler gaps require a different approach: walk the docs the way a customer would. Pick a task. Try to complete it using only what’s there. Count how many times you get blocked. Then take the specific problems that surfaced in your interviews and try to solve them using the docs. Can you? If not, that’s your gap list.

This is slow work, but it’s irreplaceable. Analytics can tell you where users drop off. Interviews can tell you what they’re struggling with. But actually walking the path yourself is how you find the places where the docs technically exist but still fail the reader.

Triage: not everything missing needs to be written right now

The first filter is pattern recognition. What kept surfacing in your interviews? What also blocked you when you walked the docs yourself? When the same problem shows up in multiple places, it earns priority.

But triage gets complicated when the loudest ask isn’t actually the most urgent gap. Recently, the noise was all about SDK docs. That seemed like the priority, until I looked at the full picture. Most customers interact with the product through the UI, and the UI was almost entirely undocumented. The reason no one was asking about it was that internal teams had quietly started using the external docs to fill their own gaps, which made the SDK docs feel more critical than they were.

And underneath all of it, the API reference was missing most of its endpoints. You couldn’t walk through a basic flow. That’s not a gap. That’s a foundation problem, and it had to come first.

The map is what makes this visible. Without it, you’re responding to whoever is loudest. With it, you can see the difference between what people are asking for and what actually needs to happen first.

Making the work visible

Here’s the part nobody talks about openly. The pressure to show visible progress fast doesn’t just feel inconvenient — it feels like dismissal. Like the work you’re doing doesn’t count until there’s a new page to point to. If thorough documentation were easy, it wouldn’t have been in the state you inherited it in.

The pressure surfaces in specific ways: constant status check-ins, public accountability for timelines that were never realistic, the implicit message that analysis isn’t work. And it has real consequences. It’s why so many technical writers paper over problems instead of fixing them. They’ve been conditioned to protect themselves and ship something visible rather than fix the actual problems. Shipping something visible is safer than explaining why the invisible work matters.

The lift and shift I described earlier did double duty. It wasn’t just a content strategy. It was a visibility strategy too. Rather than announcing a gap analysis, the reorganization itself became the artifact. Moving content into a logical structure gave stakeholders something concrete to see without requiring me to explain the process behind it. And when I instructed the AI to move content, I built in a pass for light cleanup: tighten the writing, fix obvious inconsistencies. The surface improved while the structure was being built. That’s not the same as papering over. The structure was the real work, and the cleanup came along for the ride.

Making complex work legible to people who weren’t in the room for it is what technical writers do every day. Turn it on yourself. Share what you’re finding as you find it. Frame the gap map as a deliverable, not as prep work. Translate the problems you’re uncovering into language that connects to what your stakeholders actually care about: user impact, support volume, product credibility. You’re not asking for patience. You’re showing your work.

Document yourself

Too many writers skip this step, and it usually starts at the beginning. It’s not modeled in the field, it’s not taught, and most job descriptions don’t ask for it. So writers focus on the work in front of them. Nobody tells them to build a paper trail. By the time anyone thinks to ask for metrics or a record of progress, it’s too late — the history isn’t there and the habit never formed.

There’s also something harder underneath it. “Writer” is in the job title, which means everyone assumes that’s the whole job. Anyone can write. They could do it themselves. The implication is that what you bring isn’t expertise. It’s just a preference.

Graphic designers faced the same dismissal until they stopped defending the art and started defining the discipline. The title shifted. The scope became visible. “It’s just art” didn’t survive contact with information hierarchy, user research, and systems thinking.

The best technical writers aren’t just good writers. In fact, leading with writing ability is almost beside the point. The role is research, information architecture, user advocacy, content strategy. The writing is how that expertise gets delivered, not what the expertise is. But until the field makes that visible, consistently, as a practice, the title will keep doing the defining for us.

Writers haven’t done that yet, not consistently. The gap analysis is a place to start. Not as a performance, but because the work genuinely is complex, genuinely does take time, and the people around you can only respond to what they can see. You inherited a mess. You mapped it, triaged it, and made a case for fixing it the right way. That’s not just writing. Show them what it is.