The developer quits: which 5 documents keep the project alive?

Picture a retailer that hired an outside team to build its order system (a hypothetical scenario for illustration, not a Click Star client). After 2 years, the lead engineer quits. The new hire opens the code and cannot tell how to run it, why this database was chosen, or what to do when it stops at midnight.

This article covers the minimum documentation that helps a software project survive that moment: a README, an architecture overview, ADRs, runbooks and a handover file. Sources: Diátaxis, Michael Nygard's essay, and guidance from AWS, Google and GitHub, checked on October 24, 2026.

It answers 3 questions: which documents to write, who keeps them accurate, and what to do in the first 30 days.

Key points

• Losing the code's author means losing knowledge, not just labor. A 2016 study of 133 popular GitHub projects estimated that 65% have a "truck factor" of 2 or less.
• Click Star's minimum set has 5 items: a README (how to run it), a 1-page architecture overview, ADRs (why this choice), runbooks (incidents) and a handover file.
• An ADR records only important decisions, briefly. When the team changes its mind, write a new ADR instead of editing the old one.
• Diátaxis splits documentation into 4 kinds: tutorials, how-to guides, reference and explanation. Mixing them on 1 page is a common mistake.
• Documents should live next to the code, change with it, and have an owner and a review date. Stale documents mislead readers.
• Never put passwords or keys in documents. Ask someone new to the project to run it from the documents.

What a project loses when the code's author leaves

A project loses 2 things: the how and the why. The how is running, deploying and fixing. The why is the reason the system was built this way.

In "Documenting Architecture Decisions" (November 15, 2011), Michael Nygard writes that a newcomer who does not know the reasons has only 2 choices: blindly accept a decision or blindly change it. A team that accepts too much it does not understand, Nygard writes, becomes afraid to change anything.

On evidence, Guilherme Avelino and colleagues posted a paper on arXiv (a server for scientific drafts) on April 22, 2016; it was accepted at the ICPC 2016 conference. They define the "truck factor" as the minimum number of people who must leave before a project is incapacitated. Across 133 popular GitHub projects, 65% have a truck factor of 2 or less.

Limits: these are well-known open-source projects, an algorithm estimates the values, and only 53% of valid developer answers agreed or partly agreed. There is no comparable measurement for Vietnam.

Software project documentation: what the minimum set contains

Google's Documentation Best Practices guide says a small set of fresh, accurate documents beats a large pile of documents in disrepair.

Below is Click Star's reference framework, not taken from an outside source. Each document answers 1 question from the person who takes over.

• README: what the project does and how to run it on a new machine.
• 1-page architecture overview: the system's blocks, where data flows, which outside services it connects to.
• ADR: why this tool or approach was chosen over the alternatives.
• Runbook: what to check and do when an incident happens, in what order.
• Handover file: which systems and accounts, who holds access, whom to contact. Record where keys are kept, never the values.

README: can a newcomer run the project

A README is the introductory file in a project folder. According to GitHub Docs, it typically says what the project does, why it is useful, how to get started, where to get help and who maintains it.

GitHub advises keeping it to what is needed to get started, with longer documentation in a wiki (a shared team pages site). Google's README guidance adds points of contact and status (such as no longer recommended).

Click Star's test: ask someone who has never worked on the project to run it from the README on a clean machine. Wherever they get stuck is what the README is missing.

ADR: recording why a choice was made

An ADR (Architecture Decision Record) is a short file recording 1 important decision and its reasons. According to adr.github.io, a project's ADRs together form its decision log.

Nygard proposes 5 parts for each ADR: title, context, decision, status and consequences. Each is 1 to 2 pages and is stored with the code.

Which decisions deserve an ADR? Nygard and AWS both list those affecting structure, non-functional requirements (such as security), dependencies (coupling between components), interfaces and construction techniques (libraries, tools). Microsoft Learn (page shows "Last updated on 2026-04-13") adds hard-to-reverse choices, and advises recording alternatives that were ruled out.

According to AWS Prescriptive Guidance, an ADR in the "Proposed" state is reviewed by the team, then accepted, or rejected with a reason. AWS states that an accepted ADR is not edited. With new insight the team proposes a new ADR and the old one becomes "Superseded". Nygard also keeps the old one so later readers see what was decided before.

Runbook: the steps to take when the system fails

A runbook describes the steps to reach 1 specific outcome. According to AWS Well-Architected (OPS07-BP03), at its simplest it is a checklist. AWS asks it to state the desired outcome, tools and permissions needed, error handling, escalation and an owner.

AWS separates runbooks from playbooks. According to AWS (OPS07-BP04), a playbook guides investigation of an incident to find the root cause, while a runbook is the procedure that deals with that cause. Google SRE (its site reliability engineering teams) uses 1 word, playbook, for both.

AWS advises having another team member run a runbook before it counts as done. Detail level is debated: per the Google SRE Workbook (On-Call chapter, on incident duty), some Google engineers want general entries that change less, others want step-by-step. If a playbook is the same commands every time, the book recommends automating it.

Click Star already has separate articles on website monitoring and on backup and recovery. A minimum runbook (Click Star's reference framework) holds: the symptom, how to confirm it, response steps in order, when to call someone else, and how to check the fix.

Diátaxis: why documentation is often hard to read

According to the Diátaxis introduction (diataxis.fr), there are 4 kinds of documentation for 4 different needs, each written in its own way.

• Tutorial: a lesson that leads a newcomer by the hand; they do the work and gain skill.
• How-to guide: solves a real-world problem for someone who already has the craft.
• Reference: neutral, complete description of the product, such as an API or functions.
• Explanation: context and reasons, answering "why".

By the Diátaxis compass, tutorials and explanation serve study, while how-to guides and reference serve the work at hand. Diátaxis says blurring the boundaries between these kinds underlies a vast number of documentation problems. Per its Reference page, reference should only describe; to instruct or explain, link elsewhere.

Diátaxis does not mention ADRs or runbooks on the pages read. The mapping is Click Star's: README first-run steps resemble a tutorial; a runbook is a how-to guide; API description is reference; ADRs and architecture are explanation.

Who keeps documents from going stale

Stale documents do harm because they look trustworthy even when wrong. Google's guidance says dead documents misinform and slow people down.

The book Software Engineering at Google (Documentation chapter) recounts that ownerless wiki pages went obsolete and duplicated each other.

After documents moved into source control, with owners and code-style review, quality improved markedly. The book advises treating documents like code: policies, source control, owners, changes with the code, tracked bugs, periodic checks.

Google's guidance asks for doc changes in the same change as the code, and, if docs are in bad shape, to delete what is certainly wrong first. The Software Engineering at Google book adds that Google records an owner and a review date in each document, with reminders after a long gap (for example 3 months).

Never put secrets in documents

READMEs, wikis and operations notes easily collect a pasted password or API key. According to GitHub Docs, secret scanning checks the whole Git history on all branches, plus issues, pull requests, discussions and wikis.

Public repositories are scanned for free; private organization repositories need GitHub Secret Protection on Team or Enterprise Cloud. When a key leaks, GitHub advises rotating it immediately.

So documents should say where a key is kept and who grants access, never the value. Click Star already has a separate article on managing API keys and secrets.

What this means for Vietnamese businesses

In Click Star's observation (no measurement), small businesses hire outside teams or have only 1 or 2 technical people in-house, so knowledge sits with very few people. For outsourced work, documentation should be a deliverable with acceptance criteria, for example the buyer's own person can run the project from the README on a clean machine.

Click Star's article on custom software lists contract handover items: code repository with history, architecture documents, data model, API description, operating guide, infrastructure account access. Code ownership is a legal question: ask a lawyer.

Click Star builds custom software, so it has an interest in this topic; these requirements should apply to every vendor, Click Star included.

Click Star's view. For a small project, the README and runbooks for common incidents pay off soonest. Start ADRs with a few recent decisions, not all history. Click Star prefers few documents that are correct, and treats a stranger running the project as a more reliable test than page count.

How to measure

Click Star's reference framework, no shared standard; compare the team against itself over time.

• First-run time: from when someone new to the project gets the README until it runs on their machine.
• Decisions with an ADR: among recent major decisions, how many have an ADR.
• Review date: which documents have an owner, and which are overdue by the team's own rule.
• After each incident: was a runbook used, which step was wrong or missing, was it fixed.

30-day plan

Click Star's reference framework, not from an outside source, to rescue knowledge held by 1 or 2 people before they leave.

• Week 1: list systems, accounts and access holders; run the project on a clean machine and draft a README; ask the person leaving.
• Week 2: finish the README with the stranger test; write runbooks for the 3 latest incidents; record where keys are kept.
• Week 3: draw a 1-page architecture; write ADRs for the latest major decisions; store ADRs in docs/decisions.
• Week 4: have someone outside the project run it from the documents; set an owner and review date per document; add an "updated the docs" line to the checklist.

Common mistakes

1. Leaving documents without an owner or review date while the code keeps changing.
2. Editing an old ADR when the team changes its mind, losing why a different choice was made before.
3. Writing a runbook that nobody but its author has run.
4. Pasting passwords, keys or connection strings into a README or wiki.
5. Mixing tutorial, explanation and reference on 1 page.

What is not known

Click Star has no independent measurement of the cost of lost knowledge when a project's keeper leaves, in Vietnam or elsewhere. The truck factor study was done in 2016 on open-source projects.

The right review cycle, runbook detail and number of ADRs have no shared standard, and Click Star found no measurement of the benefit of each kind of document.

The secret scanning conditions were read from 1 GitHub Docs page and may change by plan.