From chaos to clarity: a process to organize legacy documentation

Inheriting a documentation mess is a rite of passage for content designers and technical writers. Whether the team finally realized they needed a dedicated role or the last writer ran away at the sight of the subject matter, you’re wading through content created by different people over time without a centralized strategy or structure.

How to create structure amid complexity

To fix documentation, we have to look past the words on the page and create a structure that shows how the pieces fit together.

Information architecture (IA) is the practice of organizing and labeling content within a system so people can find and understand what they’re looking for. It includes how content is classified, structured, and connected to help people accomplish specific tasks. IA is an ongoing process that requires regular reflection and revision.

1. Name all the things

Step one is as simple as it sounds. Name all the things. List everything your team owns. This could be services, products, applications, or integrations. On my team, I use the term “components” to capture everything we work on in digital identity services. 

While putting these words to paper (or sticky notes), you’ll identify duplication and inconsistencies. This first step is all about reaching alignment on what these things are actually called.

2. Research user needs

Understanding different stakeholder contexts is essential to breaking technical and complex concepts into accessible and informative content. A few simple exercises can tell you who your content is for and how it’s used. 

For example, I’m currently working on authentication and identity for VA.gov. I recently did research with product, engineering, and UX team members on my team where I asked questions about their role, documentation they share most often, and the people they work with. 

To build structure around the components we identified in step one, I included a card sorting exercise. Participants arranged individual components into groups and gave each of those groups a name. This reveals insights into the team’s existing mental models and the relationships between our different services. 

Depending on their role, the groups and labels team members created could vary quite a lot. Based on this research we created a distinct onboarding component to help each audience with wayfinding. Our IA needs to respond to the top use cases our team supports for our services. Everyone gets a single starting point with a clear path forward (because in theory, every page is page one).

3. Identify the experts

People are an essential part of IA. If you’re lucky, you may find a few volunteers willing to help you. Everywhere I’ve worked, I’ve come across at least one backend engineer who’s also secretly writing a novel or has an epic Substack. It’s also usually okay to volunteer folks as subject matter experts if their roles naturally align to a given topic.

Subject matter experts aren’t being coerced into part-time technical writer roles. They’re lending their expertise to ensure we represent our team’s work clearly and accurately over time. Putting an expert’s name in writing removes ambiguity and makes it easier to keep everything accurate and up-to-date.

4. Assess your existing content

Content audits can be utterly endless. It’s best to pinpoint a specific area of focus so you don’t try to boil the ocean. You could also time-box the exercise so you gather just enough information to get started. Steps one to three will define why your content matters to real people before you dive in and start reviewing.

For example, on my team at VA, I focused on compiling all the components that we own (services, integrations, and applications) into a single index. This is more than just a structured list, it’s a prioritized inventory of our most important content. The index links to the best resource for each component and identifies a subject matter expert. This give us a starting point to evaluate the top-level content that matters most to us. 

From this initial inventory you can take stock of what’s working well, where there might be gaps, and where you can make things more consistent. Document which types of content need to be accessible to a public audience and what needs to be stored in a private repository. Your subject matter experts provide invaluable feedback at this stage. 

5. Build guidelines as you go

Guidelines are a tool to help you bridge the gap between the content you already have and the content your audience actually needs. You don’t need exhaustive style guidelines if your organization has existing standards you can start with and build upon. 

Focus on making it easy for teammates to answer the questions that come up most often in their own contexts: When do we need documentation? Do I need to create a new doc or update an existing one? Who should review my content, and who can help me publish it? Documenting your guidelines also gives people a structured way to provide feedback or suggestions.

6. Make the process iterative

IA is a process and not an end state. You’ll always be making adjustments based on questions, changes, and input from others. Communicate any major content changes in advance and include clear rationale. Make it easy to provide feedback and suggest improvements. 

In the process of cleaning up your existing content, your IA will probably change (for the better). You’ll find duplicated content, inconsistencies, and opportunities to simplify or cross-link helpful resources. The more people find and use your documentation, the more you’ll learn about how it can be improved.

Information architecture is built for change

Information architecture is never perfect. You’re drawing clean boundaries around things that don’t always have them. Services overlap, teams share ownership, and the lines between components can be blurry in practice. 

Your IA is also always changing for good reasons. Your team structure, domain, or product scope may evolve. And you’re always starting new work. A well-designed IA will scale to adapt to these inevitable changes. It frames the most important work your team delivers and who it’s for.

Simpler is harder (but better)

This process of tidying up your documentation isn’t a glamorous one. As you start making changes, it takes time to clean up links and redirect duplicate pages uncovered in the process. (Though personally, I find this type of cleanup more than a little bit satisfying.)

What’s even more satisfying is when the simplicity starts to pay off. Recently, my team released a new error message. This time, our documentation only needed to be updated on one page instead of three or four. Amid consistent complexity, a strong IA steers you toward simplicity. 

Someday in the future, you may need to reinvent this IA once again. Or you’ll inherit another mess to untangle. When that day comes, stay calm, be patient, and start again at step one.