Technical debt is a term that refers to the “hidden” costs associated with a system’s architecture and codebase. These hidden costs can make software costly to change or update and may eat up resources that could be better spent elsewhere.
We’ve written about technical debt a lot. Last year, my colleagues Chris and Sarah dove into a five-part series on how to manage and prevent technical debt; another coworker, Kane, wrote a very popular piece on why developers should choose design over architecture to avoid technical debt.
Content creators and editors can face similar challenges related to accumulated debt. And like technical debt, a failure to plan for content-related debt can cause major headaches down the road. In this post, I list some potential sources of content-related debt, list ways to identify it, and then share strategies for preventing it in the first place.
Students in Washington D.C. taking part in a 1942 program to collect scrap paper.
Sources of content and documentation debt
Imagine, for instance, that you’ve been tasked with creating a handbook for your staff that outlines common team practices. Or perhaps you’re creating content that tells the public how to file a particular form. All of the following are forms of content debt that could cause you to have trouble with this task:
No documentation: Some tasks might be completed by staff without any kind of written documentation. Others might over-rely on the institutional memory of individuals.
No structure to document: Documentation might be completed, but spread out across properties in numerous formats so no one knows where to look. It might also be in various states of completion.
Siloed content development: Specific teams and projects may have developed content, but that content might not be available or findable to others.
Parallel/redundant development: Teams may have created similar content and the results may need to be merged or aligned in order to work well. They may even be conflicting statements.
Identifying the best author: Maybe someone wrote tasks down, but that person isn’t the most knowledgeable on staff about that topic. How do you connect each topic with the best individuals in your organization to write about it? What if the best person is already overworked?
Lack of ownership: Someone writes stuff down, but no one on the team takes ownership over the material — so it languishes.
Everything is written down — literally everything: Every little task is written down, creating an overwhelming experience for the reader who cannot determine what is meaningful. In addition, the entire mass of content must be managed, adding to the debt.
It’s not clear what should be written or documented, and where: Let’s say you have multiple places where content is placed. A new teammate might not know where to add new material.
Content outgrows the container: If content is quickly being created but the container it’s in doesn’t have a good information architecture that allows that content to be surfaced, then it might be difficult to find.
Team members leave before content or documentation can be completed: Rotating team members on and off a team could result in documentation not being fully developed, or too much churn for content to be completed.
Leaving content as the last step in a product process: If you think of content as something that can be added after other stages of the project are complete, then you may be creating content that’s just not necessary.
Nothing in place to ensure content is routinely updated: Is it easy for a teammate to update content? Are there product or editorial barriers in place for doing so? Are links broken?
No way to alert readers when content was last updated: Does the reader or user know when the content was last updated and that it’s accurate?
Forgetting the audience and creating unnecessary content: Creating content but not thinking about a need or the audience for the piece of content.
A product changes, the content doesn’t: When a process or product changes, updating documentation isn’t built into the process.
Lack of standards: Information is not presented in a standard fashion, making it difficult for the reader to comprehend. Or it might be confusing, meaning that people disagree about what’s actually documented.
Deliberate obstructionism: Teams or individuals want to maintain artificial importance and therefore do not detail everything needed to complete a task.
Firefighting: Putting out software fires with no time to update documentation. In other words, content is far down on the priorities list.
Beyond existing job descriptions: No one in the organization thinks documenting processes is in their job description. Or content responsibility is pushed far down the organizational chart where there may be higher turnover.
Making content nominally available: Scanning a PDF and putting it online does not mean it's accessible. (h/t Lauren Lockwood, Chief Digital Officer, City of Boston)
Using the wrong container for content: Sometimes content is better as a data set than a paragraph. Knowing which one to use is key. (h/t Lauren Lockwood)
Consequences of content and documentation debt
Buildup of content debt may not be as apparent as technical debt, because it’s unlikely to initially cause software to break. Still, it could easily result in confusion, the erosion of trust between the user and the product, a greater need for customer support, slower progress, the need for more meetings, more external and internal complaints, and wasted time getting people onboarded to teams, projects, or organizations. Thinking about content as an afterthought or postponing documentation may result in poor or no documentation if priorities shift or change.
Identifying content and documentation debt
There are a number of indicators or warning signs that can help your team identify content debt.
Slower rate of onboarding new users: In software, velocity is a measurement of how much work a development team can complete during a particular interval (for example, two weeks). If velocity starts to slow down over the course of several iterations, it maybe a sign that too much technical debt has piled up and is now impairing development productivity. Likewise, you can measure velocity by how quickly new members to a team can onboard to a task or project. If new team members start to get bogged down with documentation, can’t understand or find documentation, or have trouble updating documentation, then content is likely impairing productivity.
Measuring the velocity of questions: Measure the number of questions you’re receiving on topics that you’ve documented. If the same question is asked several times, perhaps that’s a sign that the content isn’t meeting user needs (or they’re not reading it.)
Performing a content or platforms audit: A platforms audit is equally as important as a content audit, particularly if you have multiple platforms where users are finding documentation or content. Auditing processes that lead to developing content through user research will help you determine how processes (and content) may need to change. Some questions to ask: How many platforms are we storing content on? Does every platform have a content strategy? Are we providing the same functionality on multiple platforms? Moreover: Is content difficult to find or maintain? How consistent is the content? Is it easily editable, if need be? How are we keeping track of changes or items that need to be changed? When was the last time this content was maintained?
Interviewing users: This is perhaps the most important. Ask people using your content to show you how they would find existing content or contribute new content. Ask them who approves changes and who can author posts. Their answers may indicate the direction that your content efforts should take.
Deciding what to do with content and documentation debt
After you determine what kinds of content or documentation debt your team might have, the next step is to implement fixes into future product cycles. You can either include extra time with each cycle, prioritize content in the product backlog, or dedicate an entire cycle to content fixes. We have also found it helpful to bring in new eyes on content and documentation work: the people who have developed workarounds are not going to be as helpful as the people who haven’t.
Preventing content and documentation debt
How do you minimize accumulating content debt in the first place? Here are a few ideas we found have worked for us when thinking about internal documentation and tools:
Give thoughtful consideration to architecture: Choose tags, platforms, and information architectures carefully. Changing bigger decisions is expensive and hard, and being deliberate about architecture at the beginning of a content project will save headaches later on.
Give thoughtful consideration to archiving: We use version control software so that the public can see previous versions of our material. Determining how to notify people that content is or is not up-to-date is something that should be thought about at the beginning of a project. Will this material ever be out-of-date? If so, what will happen to it? To the link? To any links that might mention this material? Who is responsible for editing or updating the material and what happens to previous versions?
Think about content early and often: Too often, documentation and content needs are brought in late into a project cycle, or content is forced to adhere to an already-existing design. This isn’t good for content creators or users. Bring the content designer onto a project early, work documentation into project cycles, and don’t let debt accumulate because it’s non-technical work. Think about review cycles for the different types of content you might create: contact information may need to be updated than Congressionally-mandated reports or a historical overview of your organization.
Measure content debt: This is where data and metrics come in. Track metrics for page traffic, 404s or errors, and reports of broken links. There are ways to automate some of these tasks.
Ensure experiences are synchronized: If you’re developing content for different platforms or different users, it’s important to ensure new content does not conflict with existing content. A thoughtful content audit can help with this.
Reducing content debt should be part of your culture: Content isn’t going to fix itself. Encourage and empower people who recognize flaws, and create communications pathways for surfacing, fixing, and editing content. A high level of trust and transparency between teams helps with this. Technical solutions can help with this. For example, what if someone deletes a page that shouldn’t have been deleted? A good technical solution ensures a) you have a backup and b) you can restore it easily.
Want more?
We’re always thinking about ways to improve content and minimize our debt. If you have suggestions, please reach out to us via Twitter @18F or by email at 18F@gsa.gov.
Thank you to Michael Hessling at the Environmental Protection Agency and Larry Gillick, the Deputy Director of Digital Strategy at the U.S. Department of the Interior for their suggestions for this post.