60. Sustainable technical documentation

Level: advanced · Reading time: 11 min · Prerequisite: book/chapters/59-risk-oriented-code-review.html · Track: supplemental · Maturity: draft · Last review: 2026-05-09

Prerequisites: book/chapters/59-risk-oriented-code-review.html. See also: book/chapters/59-risk-oriented-code-review.html, book/chapters/27-grammar.html, book/chapters/31-build-errors.html.

Concrete Problem

Delivery chapters often list CI or review steps without connecting them to the evidence they are supposed to protect.

Red Thread (Single Project)

One feature moves through local validation, CI checks, and review expectations with one visible contract.

For what

This chapter helps the reader understand delivery as proof preservation.

What you are going to do

You will inspect one feature flow, identify what local checks prove, what CI proves, and what review still needs a human decision.

Coherent example

space demo/delivery

proc validate_release(name: string) -> int {
  if name == "" { give 11 }
  give 0
}

Global explanation

Delivery pages should explain evidence flow. Local checks, CI pipelines, and review rules are useful only when the reader knows what claim each one is guarding and what kind of regression it can still miss.

Invalid case

proc broken_release(name: string) -> int {
  if name { give 0 }
  give 11
}

This invalid case is intentionally small. It exists to isolate the contract failure that the chapter is trying to teach.

Common pitfalls

• Turning CI pages into command inventories only.
• Assuming automated checks remove the need for architectural review.
• Treating documentation and code evidence as separate concerns.

Short exercise

Take the example and write one local check, one CI check, and one review question that would protect it.

Summary in 5 points

1. Delivery is proof preservation.
2. Each gate should protect a named claim.
3. Local, CI, and review evidence are not interchangeable.
4. The chapter should connect process to code.
5. Good delivery docs reduce ambiguity about readiness.