Linux & Bash · Part II · Module 35 · Reusable Flow Tooling and Hand-Off

Documenting a Flow for the Next Engineer

Advice about documentation is usually unfalsifiable, so this chapter does something else: it writes a normal README for the flow built in this module, then runs every claim in it. Four of ten were false, including a --help that performed the action it was documented to describe — and the tool that found them has a measured blind spot of its own.

Advanced25 min readLinuxPart IIDocumentationHand-OffMaintenance

Part II · Module 35 · Chapter 35.6 · Documenting a Flow

The flow from the last five chapters now has a library, a configuration file, a Makefile, a Python reporter and a generated Tcl script. Documenting it is the point at which most writing on the subject becomes advice — "explain your assumptions", "keep it up to date" — which nobody can check.

So instead: here is the README I would actually have written, and here is what happened when every line of it was run.

1. A Normal README

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

# report flow

## Usage

    $ ./drive.sh                       # defaults to chip_a
    $ ./drive.sh ok chip_b reports     # explicit top and stage
    $ ./drive.sh --help                # usage

## Exit status

    0   reports were analysed
    1   no reports found
    2   the flow itself is broken

## Requirements

    tclsh, md5

## Notes

The generated script is written to /tmp and cleaned up afterwards.
Set FLOW_NAME to change the log prefix.

Nothing about that is unusual. It has a usage block, an exit-status table, a requirements line and two notes — more than most flow scripts get. Ten factual claims.

2. Running Them

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ ./drive.sh
  rc=126
$ ./drive.sh ok chip_b reports
  rc=126
$ ./drive.sh --help
  rc=126

126 three times, which is "found, but not executable":

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ ls -l drive.sh
  mode -rw-r--r--  drive.sh

Chapter 11.1's status table: 126 is a permission problem, 127 is not found. The README's own invocation form does not work, because the execute bit was never set — and it was never set because every test during development was bash drive.sh.

Invoking it the way the author actually does:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ /bin/bash drive.sh --help
runtcl: note: running gen/report.tcl (ef2979f9) args: chip_a reports
top=chip_a stage=reports reports=3
  hold.rpt
  power.rpt
  setup.rpt
runtcl: note: flow finished rc=0
  rc=0

--help ran the flow. The case had no branch for it, so --help fell through to the default, the script generated the report script and ran it, and exited 0.

This is the worst defect of the four, and the reason is not that the output is wrong. It is that the one command a stranger types first, to find out what the script does without doing anything, performs the action. On this flow that is harmless. On Chapter 3.3's cleanup script it is not.

The remaining claims:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ /bin/bash drive.sh ok chip_a nostage ; echo $?
  measured rc=3       (README says 1)

$ ls /tmp/flow.*.tcl | wc -l
  0
$ ls -l gen/report.tcl
  EXISTS, 486 bytes, not cleaned up

#	claim	measured	verdict
1	`./drive.sh` runs it	rc 126, no execute bit	wrong
2	defaults to `chip_a`	`top=chip_a`	ok
3	`ok chip_b reports` works	`top=chip_b reports=3`	ok
4	`--help` prints usage	ran the flow, rc 0	wrong
5	`0` = reports analysed	rc 0	ok
6	`1` = no reports found	rc 3	wrong
7	`2` = the flow is broken	rc 2	ok
8	needs `tclsh`, `md5`	both present	ok
9	script goes to `/tmp`, cleaned up	`gen/report.tcl`, kept	wrong
10	`FLOW_NAME` changes the prefix	`timing: note: …`	ok

Four of ten. And none of the four is a typo or a slip of attention:

#1 is a difference between how the author runs it and how the document says to.
#4 is a feature the document describes and the script does not have.
#6 is a status the document remembers from an earlier design.
#9 is a sentence that was true about the version Chapter 35.5 replaced.

And the four cases the README does not mention at all

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ /usr/bin/grep -nE '^\s+(ok|empty|broken|gone)\)' drive.sh
  5:  ok)     gen_report_script gen/report.tcl ;;
  6:  empty)  : > gen/report.tcl ;;
  7:  broken) printf 'if {1} { puts "x"\n' > gen/report.tcl ;;
  8:  gone)   rm -f gen/report.tcl ;;

The script takes four first arguments. The README documents one. A reader of the document cannot know that empty, broken and gone exist, and — worse — cannot know what happens if they type something else, because there was no *) branch either: an unrecognised argument fell through, generated nothing, and ran whatever gen/report.tcl happened to contain from the previous run.

This is the asymmetry that makes documentation hard to audit by reading. A false claim is visible in the document; a missing one is not. Every technique in this chapter finds the first kind. The only reliable way to find the second is to read the code and enumerate its branches — which is why a case with an explicit *) is a documentation feature as much as a correctness one: it turns "what happens if I type something else" into a question the script answers out loud.

3. Making the Claims Executable

A README's usage block is already almost a test. It needs one annotation — the status the author believes it produces:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

#!/bin/bash
# doctest.sh <doc> -- run every command the documentation shows, and check that
# it exits the way the documentation says.
#
# A line of the form
#     $ <command>                     #= <expected rc>
# is executed; a missing "#=" means 0 is expected. Anything else is prose.
#
#   0  every documented command behaved as documented
#   1  at least one did not
#   2  usage / unreadable
set -u
doc=${1:?usage: doctest.sh <doc>}
[ -r "$doc" ] || { echo "doctest: cannot read $doc" >&2; exit 2; }
pass=0; fail=0
while IFS= read -r line; do
  case $line in
    *'$ '*) ;;
    *) continue ;;
  esac
  cmd=${line#*$ }
  want=0
  case $cmd in
    *'#='*) want=${cmd##*#=}; cmd=${cmd%%#=*} ;;
  esac
  want=$(printf '%s' "$want" | tr -d ' ')
  cmd=$(printf '%s' "$cmd" | sed 's/#.*$//; s/[[:space:]]*$//')
  [ -n "$cmd" ] || continue
  eval "$cmd" >/dev/null 2>&1
  got=$?
  if [ "$got" = "$want" ]; then
    printf 'doctest: ok    rc=%s  %s\n' "$got" "$cmd"
    pass=$((pass+1))
  else
    printf 'doctest: WRONG want rc=%s got rc=%s  %s\n' "$want" "$got" "$cmd" >&2
    fail=$((fail+1))
  fi
done < "$doc"
printf 'doctest: %s ok, %s wrong\n' "$pass" "$fail"
[ "$fail" -eq 0 ] || exit 1

Run against the README as written, every claim unannotated and therefore expected to succeed:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

doctest: WRONG want rc=0 got rc=126  ./drive.sh
doctest: WRONG want rc=0 got rc=126  ./drive.sh ok chip_b reports
doctest: WRONG want rc=0 got rc=126  ./drive.sh --help
doctest: 0 ok, 3 wrong
  rc=1

And with the README's own claimed statuses written in:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

doctest: ok    rc=0  /bin/bash drive.sh
doctest: ok    rc=0  /bin/bash drive.sh ok chip_b reports
doctest: WRONG want rc=2 got rc=0  /bin/bash drive.sh --help
doctest: WRONG want rc=1 got rc=3  /bin/bash drive.sh ok chip_a nostage
doctest: ok    rc=2  /bin/bash drive.sh empty
doctest: 3 ok, 2 wrong
  rc=1

Proven able to fail on five separate claims across the two runs — which is the standard Chapter 21.8 sets for any checker, and the reason to show the red output before the green.

The audit says a claim is wrong; it does not say which side to change

This is the part that is easy to get backwards. Of the four defects, two were the document's fault and two were the script's:

defect	fix the	because
`--help` runs the flow	script	a documented inspection command must not act — the document was describing the right behaviour
`./drive.sh` → 126	script	`chmod +x`; the document's invocation form is the correct one to standardise on
`1` vs `3` for no data	document	`1` means a failing test (Chapter 21.4); the script's `3` is right
`/tmp` and cleanup	document	the sentence describes a design Chapter 35.5 deliberately abandoned

So the audit's value is not that it makes the document true. It is that it forces a decision about which of the two is wrong, and in half the cases here the answer was the code. A document written from the behaviour would have silently blessed --help.

The --help fix is the one worth copying, because it is also the chapter's main documentation technique:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

usage() {
  cat >&2 <<'USAGE'
usage: drive.sh [ok|empty|broken|gone] [top] [stage]
  ok      generate the report script and run it   (default)
  empty   simulate a generation that wrote nothing
  broken  simulate a generation that stopped mid-brace
  gone    simulate a generation that wrote no file
exit status: 0 ran and succeeded
             2 the flow is broken; the interpreter was NOT launched
             3 the script ran and exited non-zero
environment: FLOW_NAME  prefix on this flow's own messages (default: runtcl)
USAGE
  exit 2
}
case ${1:-ok} in -h|--help|help) usage ;; esac

with *) usage ;; added to the main case. That is a quoted heredoc (Chapter 35.5) inside the script, so the usage text cannot drift from the script's location — it moves when the script moves and is deleted when the script is deleted. The README can then be short, because the authoritative list of arguments is one --help away rather than copied.

After fixing each defect on its correct side, and documenting the four cases:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

doctest: 10 ok, 0 wrong
  rc=0

doctest checks commands. Most of a README is prose, and prose is not executable:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

The flow reads its stage from the `CONF_STAGE` setting and requires a licence.
Reports older than 24 hours are regenerated automatically.
The generated script is deleted after a successful run.

    $ ./drive.sh                                   #= 0
    $ ./drive.sh --help                            #= 2

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

doctest: ok    rc=0  ./drive.sh
doctest: ok    rc=2  ./drive.sh --help
doctest: 2 ok, 0 wrong
  rc=0

Three false claims, zero complaints. Each is false in the strongest possible sense — the words do not appear in the code at all:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

CONF_STAGE: drive.sh:0 runtcl.sh:0
licence:    drive.sh:0 runtcl.sh:0
24 hours:   drive.sh:0 runtcl.sh:0
deletion:   1  (only in the 'gone' simulation)

This is the same shape as Chapter 35.5's info complete and bash -n: a check that verifies structure and cannot verify meaning. Stating the blind spot is part of shipping the tool, because a green doctest on a README full of invented prose is a stronger false assurance than no check at all.

One slice of the prose is mechanically checkable, though — the identifiers it names:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

#!/bin/bash
# refcheck.sh <doc> <script>... -- every identifier the doc names in backticks
# must appear in at least one script. Catches documentation that describes a
# variable, function or flag the code does not have.
set -u
doc=${1:?usage: refcheck.sh <doc> <script>...}; shift
[ $# -ge 1 ] || { echo "refcheck: need at least one script" >&2; exit 2; }
miss=0
for id in $(/usr/bin/grep -o '`[A-Za-z_][A-Za-z_0-9]*`' "$doc" | tr -d '`' | sort -u); do
  if /usr/bin/grep -qw -- "$id" "$@"; then
    printf 'refcheck: ok      %s\n' "$id"
  else
    printf 'refcheck: MISSING %s (named in %s, in no script)\n' "$id" "$doc" >&2
    miss=$((miss+1))
  fi
done
printf 'refcheck: %s missing\n' "$miss"
[ "$miss" -eq 0 ] || exit 1

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

refcheck: MISSING CONF_STAGE (named in README4.md, in no script)
refcheck: ok      FLOW_NAME
refcheck: ok      run_tcl
refcheck: ok      tclcheck
refcheck: 1 missing
  rc=1

A document that names a variable, function or flag the code does not have is wrong in a way a machine can see — which covers the commonest drift of all: a setting that was renamed.

My first `refcheck` read two of four identifiers and said nothing

The version above is the fixed one. The first used sed:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

for id in $(sed -n 's/.*`\([A-Za-z_][A-Za-z_0-9]*\)`.*/\1/p' "$doc" | sort -u); do

On a document naming four identifiers:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

  doc names:  CONF_STAGE FLOW_NAME run_tcl tclcheck
  sed -n s/:  CONF_STAGE tclcheck

Two of four, silently. sed's s/// substitutes once per line, and the leading .* is greedy — so on a line containing two backticked identifiers, .* swallows the first one and the capture lands on the last pair. FLOW_NAME and run_tcl were each the first on their line, and were skipped.

It reported 1 missing and exited 1, which looked like a working check. The output was even correct about CONF_STAGE. Right answer, half the input — and if the renamed setting had happened to sit first on its line, the check would have passed clean.

grep -o prints every match on every line, which is the fix:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

for id in $(/usr/bin/grep -o '`[A-Za-z_][A-Za-z_0-9]*`' "$doc" | tr -d '`' | sort -u); do

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

refcheck: MISSING CONF_STAGE …
refcheck: ok      FLOW_NAME
refcheck: ok      run_tcl
refcheck: ok      tclcheck

Four of four. The general rule, and this is the third time Part II has met it: sed s/// without g is one replacement per line, and a greedy .* in front of a capture makes it the last match rather than the first. Chapter 13.6 measured the g half; this is the greedy half, and the two combine into a checker that quietly reads a fraction of its input.

The tell was comparing the tool's output against an independent count of its input. Nothing in the tool's own output suggests two identifiers went missing.

5. What the Document Should Contain

With both checks in place, the question "what goes in it" has a sharper answer than "the assumptions": everything a stranger cannot get by running --help, plus everything --help says, in a form the audit can check.

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

# report flow

Generates a Tcl report script, checks it, runs it, and keeps it.

## Run it

    $ ./drive.sh                                   #= 0
    $ ./drive.sh ok chip_b reports                 #= 0
    $ ./drive.sh --help                            #= 2

## Exit status

    0  the script ran and exited 0
    2  the flow is broken -- the interpreter was NOT launched
    3  the script ran and exited non-zero (no reports, or no stage directory)

Never 1. In this flow 1 means a failing test, and this step does not run tests.

    $ ./drive.sh ok chip_a nostage                 #= 3
    $ ./drive.sh empty                             #= 2
    $ ./drive.sh nonsense                          #= 2

## What it writes, and what it keeps

`gen/report.tcl` is the generated script. It is **not** deleted: it is the only
record of what the tool was asked to do, and it can be re-run by hand with no
bash involved --

    $ tclsh gen/report.tcl chip_a reports          #= 0

Its md5 is logged on every run. The same inputs give the same digest, so
"did the tool get the script I think it got?" is a comparison, not an argument.

## Settings

`FLOW_NAME` prefixes this flow's own messages (default `runtcl`).

    $ FLOW_NAME=timing ./drive.sh                  #= 0

## Requirements

`tclsh` (8.5 or later) and `/sbin/md5`, which `run_tcl` calls by absolute path
so that PATH cannot change the answer.

## Known failure modes

- A generation that writes nothing still leaves a file, because `>` truncates
  before the command runs. `run_tcl` rejects an empty script rather than
  running it, because an empty Tcl script exits 0.
- `tclcheck` checks structure, not names: it rejects an unbalanced brace and
  accepts a call to a command that does not exist.
- The stage argument is not validated by the shell. `report.tcl` checks it and
  exits 3.

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

doctest:  8 ok, 0 wrong      rc=0
refcheck: 0 missing          rc=0

Five sections, and each earns its place for a reason this module measured:

Run it — the commands, annotated, so doctest covers them. Three lines, because the authoritative argument list is in --help.

Exit status — with the reason 1 is absent. A table of numbers is copied wrong — claim #6 in §2 above; a table with "1 means a failing test and this step does not run tests" survives a rewrite, because the next engineer can regenerate it from the rule.

What it writes, and what it keeps — the non-obvious decision. gen/report.tcl surviving looks like an oversight until the sentence explains that it is the only record of what the tool was asked to do. Undocumented deliberate behaviour gets helpfully "fixed" by the next person, which is the failure mode Chapter 28.1 measured from the other direction.

Settings — one line per variable, each with its default and a runnable example, so refcheck can see the name and doctest the behaviour.

Known failure modes — the three that cost real debugging time this module: the zero-byte artefact from > truncating early, tclcheck checking structure and not names, and the stage argument being validated by Tcl rather than by the shell. This is the section nobody writes and the only one with a measurable payoff: each entry is a debugging session the next engineer does not repeat.

And what is deliberately not there: the argument list (it is in --help), the internal design (it is in the script's own CONTRACT block from Chapter 35.1), a change log (that is git log), and anything about why the flow exists, which belongs to the project and not to the script.

6. Where Each Kind of Fact Lives

Figure 35.6.1 — Four places a fact can live, and the test for each

A fact in the wrong place drifts. The test is who has to change when the script changes: the usage block and the contract move with the code, the README is audited against it, and git answers history.

The operative test is who has to change when the script changes. A fact in --help or a CONTRACT block changes in the same edit as the code, in the same file, under the same review. A fact in the README changes in a different file and is therefore the one that drifts — which is exactly why the README is the part that gets audited, and why it should hold as little as it can.

Practice

Write the README you would normally write for a script you already have.
Count its factual claims.
Run every command in it exactly as written.
Check whether your script is executable, and how you have been invoking it.
Run your documented --help and confirm it does not act.
Check every exit status in your status table.
Check every statement about files written or removed.
Tally the defects and classify each by cause.
Enumerate your script's case branches and compare against the document.
Check for a *) branch, and add one if it is missing.
Say why a missing claim is harder to find than a false one.
Write a doctest that runs annotated commands and checks statuses.
Show it failing before you show it passing.
For each defect, decide which side is wrong and say why.
Move the usage text into the script as a quoted heredoc.
Add *) usage ;; and re-run the audit.
Write three false prose claims and confirm doctest passes.
Grep the code for each one to show how false they are.
State your doctest's blind spot in its own documentation.
Write a refcheck for backticked identifiers.
Compare its output against an independent count of the identifiers in the document.
If you used sed s///, check how many matches per line it took.
Rewrite it with grep -o and compare.
Write the five-section document and get both checks green.
Give the reason behind your status table, not just the numbers.
Document one deliberate behaviour that looks like a bug.
Write a known-failure-modes section from this module's debugging.
List what you deliberately left out, and where each of those facts lives.
Apply the who-has-to-change test to every fact in your document.

Check Your Understanding

How many claims did the normal README make, and how many were false?
What does exit status 126 mean, and why did it appear three times?
Why had the execute bit never been set?
What did --help do, and why is that the worst of the four?
What status did "no reports found" actually produce?
Where was the generated script, and what had the README said?
Classify each of the four defects by cause.
How many case branches did the script have, and how many were documented?
What happened for an unrecognised argument, and why?
Why is a missing claim harder to find than a false one?
What single annotation makes a usage block testable?
On how many claims was doctest proven able to fail?
For each of the four defects, which side was wrong?
Why would a document written from the behaviour have been worse?
Why put the usage text inside the script as a quoted heredoc?
What does *) usage ;; contribute to documentation?
What did doctest say about three invented prose claims?
How false were they?
Which earlier tools share that blind spot?
Why must the blind spot be stated rather than left implicit?
What slice of prose is mechanically checkable?
What did the first refcheck read, and what did it report?
Why did sed capture the last identifier on a line rather than the first?
Why did the bug look like a working check?
What is the fix, and what is the general rule?
How was the bug detected at all?
Name the five sections of the model document and the reason for each.
Why give the reason behind a status table?
What happens to undocumented deliberate behaviour?
Which section has the most measurable payoff?
What is deliberately left out, and where does each of those facts live?
State the who-has-to-change test and what it predicts.

Answers

Ten claims; four false.
Found but not executable. Three times because the README's invocation form was ./drive.sh and the file was mode -rw-r--r--.
Because every test during development used bash drive.sh, which does not need it.
It ran the flow and exited 0. Worst because the one command a stranger types to find out what a script does without doing anything performed the action — harmless here, not on a cleanup script.
3, not the documented 1.
gen/report.tcl, 486 bytes, kept; /tmp held zero matching files. The README said it went to /tmp and was cleaned up.
A difference between how the author runs it and what the document says; a feature the document describes and the code lacks; a status remembered from an earlier design; and a sentence that was true of the version 35.5 replaced.
Four branches; one documented.
It fell through with no *) branch, generated nothing, and ran whatever gen/report.tcl held from the previous run.
Because a false claim is visible in the document and a missing one is not — finding it requires reading the code and enumerating its branches.
The expected exit status, written as #= N.
Five — three 126s, then --help (2 vs 0) and nostage (1 vs 3).
--help and the execute bit were script defects; the 1 vs 3 status and the /tmp sentence were document defects.
Because it would have silently blessed --help running the flow.
So it cannot drift from the script's location — it moves when the script moves and is deleted when the script is deleted.
It turns "what happens if I type something else" into a question the script answers out loud, instead of one only the code can answer.
2 ok, 0 wrong — it passed.
Completely: CONF_STAGE, "licence" and "24 hours" each appear zero times in either script.
info complete and bash -n — both verify structure and cannot verify meaning.
Because a green check on a document full of invented prose is a stronger false assurance than no check at all.
The identifiers it names — a variable, function or flag the code does not have is wrong in a way a machine can see.
Two of four identifiers; it reported 1 missing and exited 1, which looked like a working check.
s/// substitutes once per line and the leading .* is greedy, so it swallows everything up to the last backtick pair.
Because its answer about CONF_STAGE was correct — right answer, half the input. A rename that happened to sit first on its line would have passed clean.
grep -o, which prints every match on every line. The rule: sed s/// without g is one replacement per line, and a greedy .* before a capture makes it the last match rather than the first.
By comparing the tool's output against an independent count of the identifiers in its input — nothing in its own output suggested anything was missing.
Run it (annotated, so doctest covers it); Exit status (with the reason 1 is absent); What it writes and keeps (the non-obvious decision); Settings (name, default, runnable example); Known failure modes (the debugging sessions not to repeat).
Because a table of numbers gets copied wrong, while a rule can be regenerated by the next engineer.
It gets helpfully "fixed" by the next person.
Known failure modes — each entry is a debugging session somebody does not repeat.
The argument list (--help), the internal design (the script's CONTRACT block), the change history (git log), and why the flow exists (the project, not the script).
Who has to change when the script changes. Facts that change in the same edit as the code — --help, CONTRACT — do not drift; facts in a separate file do, which is why the README is the audited part and should hold as little as possible.

7. Remember

A normal README made ten claims and four were false — and not one was a typo.
./drive.sh exited 126: the documented invocation form had never been run, because development used bash drive.sh.
The documented --help ran the flow. The command a stranger types to look without touching performed the action.
The status table said 1 for no data; the script said 3. The script was right — 1 means a failing test.
"Written to /tmp and cleaned up" was true of the version 35.5 replaced. Documentation decays by being correct about the past.
Four case branches, one documented, and no *) — a false claim is visible in the document, a missing one is not.
Annotate each usage line with its expected status and the usage block becomes a test suite. doctest was proven able to fail on five claims.
The audit says a claim is wrong, not which side to change — here two were the script's fault and two the document's.
Put the usage text in the script as a quoted heredoc, and add *) usage ;; so it cannot drift from the code.
doctest passed three completely invented prose claims. Say the blind spot out loud; a green check on invented prose is worse than no check.
refcheck read two of four identifiers and still looked right. sed s/// is one replacement per line, and a greedy .* lands the capture on the last match — use grep -o.
Five sections: run it, exit status with its reason, what it keeps and why, settings, known failure modes. Leave out the argument list, the design, the history and the rationale.
Document deliberate behaviour that looks like a bug, or the next person will fix it.
Who has to change when the script changes? Facts that move with the code do not drift; the README is the part that does, so keep it small and audit it.

8. What Is Next

The flow is now built, bounded, measured and documented — which is the state it is in on the day it is handed over, and not the state it stays in. Chapter 35.7 turns the whole of Part II into the review a flow script should pass before anybody else depends on it, applied to real scripts with real defects rather than to a list of principles.

Where this fits

Part of the Linux & Bash curriculum.

1. A Normal README

2. Running Them

3. Making the Claims Executable

4. The Blind Spot

5. What the Document Should Contain

6. Where Each Kind of Fact Lives

Practice

Check Your Understanding

7. Remember

8. What Is Next

Where this fits