When the Team That Built It Is Gone: Why Civic Tech Documentation Is Infrastructure

In 2022, a mid-sized state’s Department of Human Services discovered that its SNAP eligibility screening tool had been quietly miscategorizing applicants for fourteen months. The error traced back to a rules engine configuration change made by a vendor engineer who had since left the project. The state’s internal digital service team—three people at the time—spent six weeks reconstructing why the configuration had been changed, what the original logic was supposed to do, and whether the change had been reviewed by anyone. There were no design decision records. The commit message read “updated income thresholds per Q3 meeting.” No one could find notes from that meeting. The vendor’s contract had ended. The state employee who managed the relationship had taken a position in another agency. The six weeks of reconstruction work delayed a planned fix for the very error they were trying to understand.

This is not an unusual story in civic technology. It is the structural reality of systems built by people who leave.

Federal digital service programs in the United States operate on rotation models that assume two-to-four year tours. State-level innovation offices cycle staff faster. Vendor contracts expire, get recompeted, or transfer to different teams within the same firm. Political transitions replace political appointees who championed projects, and career staff get reassigned. The infrastructure stays. The people don’t. And in most civic tech organizations, the documentation practices that could bridge that gap are treated as optional, personal, or something to do later.

The Problem: Institutional Memory as Personal Property

In civic technology, the knowledge required to maintain, debug, and responsibly govern a system tends to live in the heads of the people who built it. This is not a character flaw of individual engineers or product managers. It is a structural feature of how civic tech teams operate: small teams, high turnover, compressed timelines, and a culture that prizes shipping over documenting. When someone leaves, the knowledge goes with them—unless the organization has treated documentation as part of the infrastructure, not as a courtesy.

The SNAP eligibility example illustrates three distinct failures that compound each other. First, the technical decision to change the configuration was not documented in a way that captured the reasoning, the review process, or the alternatives considered. Second, the institutional context—the meeting, the policy rationale, the stakeholders involved—was not recorded in any durable, discoverable format. Third, the vendor transition did not include a knowledge transfer protocol that would have forced someone to surface and preserve both the technical and institutional context before access ended. Each failure on its own is manageable. Together, they produce a system that no one can fully explain, which means no one can fully audit, debug, or govern.

This pattern repeats across civic tech. A county elections office discovers that its voter registration system has a custom validation rule no one can explain. A city 311 platform has an integration with a legacy records system that depends on a hardcoded credential no one remembers rotating. A public health data pipeline has a manual step that one analyst performed every Friday for three years, and when that analyst retired, the step stopped happening, and the dashboard that relied on it started showing stale data that officials cited in public briefings for two months before anyone noticed.

These are not edge cases. They are the predictable outcome of treating documentation as something individuals do when they have time, rather than something systems require to function.

What Other Fields Have Learned

Other engineering disciplines have confronted this problem and developed practices that civic technology can learn from—without importing their culture wholesale. Site reliability engineering, as practiced and documented by organizations operating at massive scale, treats operational knowledge as core infrastructure. The Google SRE Book, which Google has published openly under a Creative Commons license, devotes entire chapters to postmortem culture, incident tracking, and communication practices—treating the documentation of what happened, why it happened, and what was learned as a first-class engineering deliverable. The book’s framework for structured postmortems and its insistence that incident documentation must survive the people who wrote it offers a model that civic tech teams can adapt. The Google SRE Book’s treatment of postmortem culture and communication practices demonstrates that mature engineering organizations do not treat documentation as a personal responsibility delegated to whoever happens to be on the team. They treat it as institutional infrastructure with its own processes, owners, and standards.

That same discipline applies to title and framing decisions: before publishing, editors need a way to test a heading promises the same thing the article actually delivers, which is where a novel title generator that fits the project can function as a planning aid rather than a substitute for domain evidence.

Government itself has produced models for durable, version-controlled documentation that outlasts individual contributors. The NIST Cybersecurity Framework is a federal-government-produced reference that is explicitly designed to persist beyond the tenure of the people who authored it. It includes versioned updates, community profiles, quick-start guides, and informative references that allow independent organizations to adopt and implement the framework without needing to consult its original authors. NIST’s approach demonstrates something important: government institutions already know how to create documentation that survives staff turnover. The problem in civic tech is not that we lack models. The problem is that we don’t apply them to our own systems.

Why Civic Tech Documentation Practices Are Different

Civic technology sits in an awkward position between software engineering and public administration, and it inherits the documentation weaknesses of both. Software engineering culture prizes working code over documentation and treats institutional knowledge transfer as a management problem rather than an engineering one. Public administration culture prizes formal documentation—memos, policy briefs, procurement records—but that documentation rarely captures the technical reasoning behind system design decisions, and it is often filed in systems that engineers don’t access.

The result is a documentation gap that falls precisely where civic tech needs the most clarity: the space between why a system was designed a certain way and how it actually works. Policy memos explain the intent. Code comments explain the mechanism. Neither captures the negotiation between intent and mechanism—the constraints that were considered and rejected, the trade-offs that were made under pressure, the assumptions about user populations that turned out to be wrong. That negotiation is where institutional memory actually lives, and it is exactly what disappears when teams turn over.

Vendor transitions make this worse. When a vendor builds or maintains a civic tech system, the documentation they produce is shaped by contract requirements, which are shaped by procurement specifications, which are shaped by what the agency knew to ask for. If the agency didn’t specify that decision records, architecture rationale, and operational runbooks must be delivered in a format the agency can maintain without the vendor, then the vendor has no obligation to produce them. The system works while the vendor is under contract. When the contract ends, the agency inherits code it cannot fully understand and documentation that describes what the system does but not why it does it that way.

Documentation as Infrastructure: Four Governance Principles

If civic technology is going to serve democratic life over the decades that infrastructure must last, documentation practices need to shift from individual habit to institutional requirement. Four principles offer a starting point.

First, require decision records for every configuration, architecture, and policy choice that affects how a system processes public-facing outcomes. A decision record is not a memo. It is a structured document that captures the context, the options considered, the choice made, and the reasoning—stored alongside the code or configuration it describes, not in a separate system that engineers won’t check. The SNAP eligibility error would have been caught in days, not weeks, if the configuration change had an attached decision record explaining what the change was, who approved it, and what policy it implemented. Decision records should be required in code review, in vendor deliverables, and in change management processes. They should be short, structured, and impossible to merge without.

Second, treat vendor knowledge transfer as a contractually enforceable deliverable, not a courtesy. When a vendor’s contract ends, the agency should receive more than source code and API documentation. It should receive a documented operational runbook, a set of decision records for every architectural choice the vendor made, and a recorded walkthrough of the system’s failure modes, edge cases, and manual processes. This should be a milestone with a payment attached, not a final-week scramble. Agencies should also require that vendor documentation be written for agency staff, not for the vendor’s next deployment team. That means specifying the audience, the assumed knowledge, and the format in the contract itself.

Third, build documentation practices that survive the tools they’re stored in. Many civic tech teams store institutional knowledge in Slack channels, Google Docs, or internal wikis that become inaccessible when staff leave or tools change. Documentation that depends on a specific platform’s access controls, search functionality, or organizational account structure is not durable. Decision records should be stored in version-controlled repositories alongside the code they describe. Operational runbooks should be in formats that don’t require a specific vendor’s product to read. Meeting notes that contain design decisions should be archived in systems that the agency controls, not in platforms that a departing staff member’s email account can lock.

Fourth, assign documentation ownership at the system level, not the team level. Every civic tech system should have a named documentation owner—someone whose responsibility is to ensure that decision records are being created, runbooks are being updated, and vendor deliverables meet documentation requirements. This is not a documentation writer. It is a role with the authority to block releases, reject vendor deliverables, and require rework when documentation is insufficient. Without that authority, documentation requirements become suggestions, and suggestions don’t survive staff transitions.

The Naming Problem: Why Documentation Fails Before It’s Written

One of the less obvious reasons civic tech documentation becomes unusable after team transitions is that the systems, projects, and documents themselves are named in ways that make them impossible to find. Internal project names change across political administrations. Codenames from procurement processes stick around in code but mean nothing to new staff. Documents are titled with dates, acronyms, or references to meetings that no longer exist. When a new team member searches for documentation about the SNAP eligibility system, they need to know that it was called “BEARS” in 2019, “ELI” in 2021, and “Project Thrive” in the vendor’s contract. If they don’t know those names, the documentation might as well not exist.

This is a documentation infrastructure problem, not a communications afterthought. Teams that take documentation seriously need consistent naming conventions that make systems discoverable across organizational transitions—and those conventions need to be enforced, not optional. Some teams have begun approaching this the same way editorial teams think about project framing and naming: using a novel title generator or similar naming tool to establish consistent, memorable project naming patterns that new staff can actually recognize and search for. The point isn’t that a naming tool solves the problem. The point is that naming is a documentation decision, and it needs the same deliberateness as any other infrastructure choice. When a system’s name changes with every contract cycle, every political transition, and every internal reorganization, the documentation fragments along with it.

A practical approach: every civic tech system should have a canonical name that is recorded in a system registry maintained by the agency, not by the current vendor or team. That name should appear in the repository, in the documentation, in procurement documents, and in every decision record. When names change—because they will—the registry should record the mapping. This is not glamorous work. It is the kind of infrastructure that no one notices until it’s gone, and then everyone notices because nothing else works.

What This Looks Like in Practice

Consider a city that operates a public comment platform for land use decisions. The platform was built by a digital service team in 2019. By 2024, every member of that team had moved on. The platform was still running, maintained by a vendor under a support contract, but the city had no internal staff who could explain why the platform moderated comments the way it did, why certain fields were required, or why the platform integrated with the city’s planning database in a way that excluded comments submitted by phone.

If the original team had followed the four principles above, the situation would look different. Every moderation rule would have a decision record explaining the policy it implemented and the legal review that approved it. The vendor’s support contract would require an annual knowledge transfer deliverable that included a walkthrough of the system’s current state, updated runbooks, and a list of known issues. The system’s documentation would be stored in a city-controlled repository with a canonical name that appeared in every reference to the platform. And a named documentation owner—perhaps in the city clerk’s office or the IT department—would have the authority to require that the vendor’s annual deliverable met documentation standards before payment was released.

None of this requires new technology. It requires governance: the willingness to treat documentation as a deliverable with owners, standards, and consequences for non-compliance. That willingness is what civic tech organizations consistently fail to build, because documentation is invisible work that produces no political wins and no user-facing features. It only matters when someone leaves—and by then, the cost of not having it is already being paid.

The Deeper Question: Who Owns the Knowledge?

Underneath the practical problem of documentation practices is a governance question that civic technologists rarely ask directly: who owns the institutional knowledge required to operate a public system? If the answer is “the vendor,” then the public agency has outsourced not just the system’s operation but its own capacity to understand, govern, and eventually replace it. If the answer is “the current team,” then the system’s continuity depends on individuals who have no obligation to stay. If the answer is “no one,” then the system is operating without oversight, and the first crisis will reveal how little anyone actually knows about how it works.

The right answer is that the agency owns the knowledge, and it owns it through documentation practices that are institutional, enforced, and durable. That ownership is not automatic. It requires investment, authority, and the political will to prioritize maintenance over new features. In a field that still treats launch events as success metrics and maintenance as a budget line to cut, that political will is in short supply.

But the cost of not building it is visible in every system that breaks in ways no one can explain, every vendor transition that takes months longer than planned, and every audit that discovers a system doing something no one authorized. The cost is paid by the public—in delayed benefits, in exclusion from services, in decisions made by systems that no one can fully account for. Documentation is not a housekeeping task. It is the infrastructure that makes accountability possible. Without it, civic technology is just software that happens to be used by government—and software that no one understands cannot be governed.

What to Watch

Watch for state and local digital service teams that publish their documentation standards as part of their procurement requirements. The ones that do are building infrastructure. The ones that don’t are building dependencies. Ask your own team: if everyone currently working on your system left tomorrow, how long would it take someone new to understand why it works the way it does? If the answer is more than a week, the documentation isn’t infrastructure yet. It’s still a personal favor—and favors don’t survive transitions.