Limit documentation to decision-relevant knowledge

What knowledge should technical documentation capture, and what should it not?

Valuable information includes purpose, system boundaries, non-obvious assumptions, discarded alternatives, data ownership, operational processes, and decision criteria. Executable configurations and tests should remain in the repository whenever possible; documents should have a target audience, owner, and test trigger instead of a blanket promise of up-to-dateness.

Concrete decision

1. Collect decisions and operational tasks for which competent personnel currently have to search for context outside the system.

2. Move automatically derivable details to code, tests, or inventory, and condense remaining knowledge in a target-group-oriented manner.

3. Set owner and audit trigger for each document and archive or remove pages without current decision relevance.

Manageable trigger

• Percentage of documents used, including target audience, specific decision, owner, and event for the next audit.

• Time to response to operational and architectural questions, as well as the number of conflicting manual copies of executable details.

Code in prose

• Code in prose Parameters, endpoints, and processes are manually duplicated and contradict the system after the next implementation change.

• Contextless decision A result is documented, but reasons and rejected alternatives are missing, and the same debate starts again later.

• Ownerless Wiki – Many pages lack a user or review date, making important current information difficult to find amidst older versions.

Non-derivable knowledge

• Non-derivable knowledge – The content explains context, intent, or limitations that are not readily apparent from the current code, schema, and automatic inventory.

• Concrete decision – A named role uses the knowledge for operation, modification, escalation, risk assumption, or architecture selection.

• Manageable trigger – Ownership and events such as releases, vendor changes, or incidents determine when the content needs to be reviewed.

Cross-check: “Code in Prose”

A wiki copies all environment variables and is outdated. The variables are automatically documented from the schema; what remains is why two unusual security boundaries exist, who is authorized to change them, and which test validates the decision.

How "Focusing Documentation on Relevant Knowledge" relates to related decisions

From "Focusing Documentation on Relevant Knowledge" Timely notification of API, plugin, and service discontinuations an important follow-up question: How do you recognize and manage the discontinuation of APIs, plugins, and services in a timely manner?

Those who want to delve deeper into "Focusing Documentation on Relevant Knowledge" from the perspective of the "Platform Strategy & Build-vs-Buy" cluster will find further information in Maintaining a robust decision file for digital systems .

If you want to practically implement "Focusing Documentation on Relevant Knowledge," you can refer to Robust Website Systems . The focus there is on "Access, Ownership, and Operational Knowledge" and "Non-Derivable Knowledge."

Conclusion: Focus Documentation on Relevant Knowledge

Good documentation adds context and decision-making capabilities to the system. The less it duplicates executable facts, the easier it is to keep truly non-derivable knowledge up to date.

Sources and Further Information

These primary sources are crucial for platform behavior, terminology, and audit boundaries when "focusing documentation on relevant knowledge."

• 14. Operate a reliable service – GOV.UK Service ManualOfficial standard for operations team, monitoring, support, security, recovery, and ongoing service responsibility.

• Governance principles for agile service delivery – GOV.UK Service ManualOfficial governance principles for clear decision-making authority, delegated responsibility, transparency, and verifiable results.