Content Strategy Begins at Home

Jordan Hirsch, Director, Strategy

The Problem

Here's a conversation that happens far too often on technology projects:

Developer 1: "Where's the documentation for this feature?"

Project Manager: "In the ticket description."
Analyst 1: "In the wiki."
Developer 2: "In the comments on the ticket."
Analyst 2: "In the email I sent you."
Client: "I have no idea."
Designer: "In an email from the client."
Tech Lead: "In our meeting notes."

Developer 1: "Uhh...thanks..."

Does this conversation sound familiar? If so, you're not alone, but you are in a bad spot. Figuring out how to store the requirements you spent all that time gathering is just as important as the gathering work itself. If you're trying to build a house, and the blueprints are scattered in 10 different places, chances are the house isn't going to get built - or at the very least the house isn't going to look much like the original plans. Your technology project is no different. Consistency in your documentation, both in format and in storage, is a key element of project efficiency and efficacy. This doesn't mean that all your requirements are going to fit into one tool. (A Jira ticket isn't always the best place for a permissions matrix, though it might be.) But it does mean making an informed decision about what kinds of documentation you produce, which tools you use to store which types of artifacts, and how you structure your information. In short, your projects need their own internal content strategy.

The Solution

OK, that heading is a lie. There isn't a single solution that's right for every project and every team when it comes to managing and storing your requirements. But there are some required elements for any solution to be successful:


Whatever methods you choose to store, tag, archive, expose, and categorize your documentation, be consistent across projects and across teams. This will be immensely helpful when a new person joins your project team (or your company) and is trying to get up to speed. This will also help everyone on the project know what is expected of them as they go about creating documentation and project artifacts. If you like to keep your meeting notes in Google Docs, your functional requirements in the wiki, and your technical tasks in Jira, that's great - just make sure that you're always following that pattern. Splitting documentation across systems isn't necessarily a bad thing (after all, different systems have different strengths and weaknesses). But if you're not being consistent in how you store your documentation (and how you create it in the first place), you are sowing the seeds of confusion.

Of course there's always room for incremental improvements (don't do something ineffective just because that's how you did it last time), but these changes should be managed (see below) and shouldn't overly disrupt the systems you have in place. If you're doing this right, not only will you save time creating your documentation, you will help ensure that documentation is easy to find and to parse by anyone on any project team - increasing everyone's efficiency.

Change Management

We're usually not lucky enough to get everything right on the first try, no matter how good a job we did listening when we were taking notes. Documentation is going to change over the course of a project. There is no one "right way" to handle change management, but the wrong way is not to handle it at all. The problems introduced when you are not managing your changes are multiplied when your documentation is split across multiple places without any consistency. Your documentation is going to change, and you should have a process in place to help you manage those changes and communicate them to your team (see below). Whether you use comments, a change log, revision dates, or something else, having a system in place to manage your changes makes it possible for everyone on your team to always know how to find the most up-to-date version of a document, what changed, when, and why.


OK, you've got a consistent scheme for how you're storing your documentation. You're using tagging and document templates to ensure consistency and make your content findable. You've implemented a versioning system so team members can clearly see when something has changed and what that change was. Great! Except... no one's following your new conventions, no one's reading the change comments, and people are emailing documents back and forth. Why? Most likely, a lack of communication. It's not enough to put these new systems and structures into place, you have to communicate with your team about them! As with any content strategy, the best time to start communicating is at the beginning, before you're locked into a system that might end up not meeting everyone's needs. Talk to your project team - find out what they need. What to the developers need most when they start on a new task? What does the project manager need access to for the weekly status reports? What do the analysts need to know about updated user stories? Treat your team like a client, and you will be able to construct a system that they will actually use.

But it's not enough to talk to people at the beginning. You need to communicate early and often when you are asking people to adopt a new system. Help your team make gradual changes. Explain why things are being done. Remind everyone about the new formats and rules, and be understanding when people don't get it right at first. Even when things are up and running smoothly, make communication a part of your process. The greatest changelog message in the world doesn't matter if no one reads it. Get your team talking to each other, so that human communication is the first thing that happens after documentation is changed. The systems and tools are in place to support this person-to-person communication. Adjust as needed, you probably don't need to email the entire team every time you fix a typo on a wireframe, but over time, your team should find its own rhythms and cadences that make the most sense for you. With good communication channels in place, managing change and keeping things consistent will happen a lot more naturally.


Managing your own documentation and content is no easy feat, but it can benefit from the same strategic thinking and user research that you would apply to any content strategy engagement (like the kind that Phase2 provides for its clients). Putting in the time to understand your team's needs will pay off handsomely as your project meets the real world and things start changing. You'll find that onboarding new team members becomes a simpler job, and your existing team members won't have to create a new way of managing documentation for each project. Content strategy to the rescue!

Jordan Hirsch

Jordan Hirsch

Director, Strategy