74. Document the documentation

Level: advanced · Reading time: 10 min · Prerequisite: book/chapters/73-team-skill-growth.html · Track: supplemental · Maturity: draft · Last review: 2026-05-09

Prerequisites: book/chapters/73-team-skill-growth.html. See also: book/chapters/73-team-skill-growth.html, book/chapters/27-grammar.html, book/chapters/31-build-errors.html.

Concrete Problem

Generic chapters without a stable scenario produce repetition and weak retention.

Red Thread (Single Project)

One small service module is used to explain the topic through input, validation, transformation, and output.

For what

This chapter helps the reader connect the topic to one concrete engineering use.

What you are going to do

You will inspect one coherent example, then one invalid variant, and extract the rule that the chapter is really teaching.

Coherent example

space demo/generic

proc run(value: int) -> int {
  if value < 0 { give 11 }
  give value
}

Global explanation

The chapter should always return to the same core question: what contract does this construct give to the full block? That is the reason every page still needs one complete, testable example.

Invalid case

proc broken(value: int) -> int {
  if value { give 11 }
  give value
}

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

Common pitfalls

• Explaining abstractions with no anchored scenario.
• Repeating template prose without changing the engineering point.
• Using invalid examples that do not isolate the chapter's real topic.

Short exercise

Take the coherent example and rewrite one line so that the chapter's central contract becomes even more explicit.

Summary in 5 points

1. Every chapter needs one concrete engineering story.
2. The contract matters more than the token list.
3. An invalid example should isolate the chapter's real lesson.
4. Global explanation beats line-by-line commentary.
5. The page should leave one reusable rule behind.