structuring-documentation

Structuring Documentation

Treat every Markdown file in scope as a documentation surface. Each one holds one subject, one content class, and a bounded amount of reading.

The surfaces in scope are the paths the user names, or the documentation files the current change touches. The script has no default scope and requires explicit paths. When no scope is stated, ask for it rather than assuming one.

Nothing here gates a build. The measurement reports; you act on what it reports.

Budgets are named values: docs.size_goal (default if not otherwise stated: 5000), docs.size_limit (6500), docs.size_ceiling (10000), docs.max_index_rows (20). When earlier context or a user instruction assigns a different value, pass it to the script as --goal, --limit, --ceiling, or --max-index-rows; otherwise run the script on its built-in defaults. When earlier context supplies a subject-ownership table for the project, use it wherever the workflow consults ownership.

Workflow

digraph doc_surfaces {
  node [shape=box];
  start [shape=doublecircle, label="editing or auditing\na doc surface"];
  scope [label="determine the surfaces in scope\n(ask when none is stated)"];
  measure [label="run measure.sh size + links"];
  subjects [shape=diamond, label="each surface holds one subject,\nowned by its directory\n(references/surface-contract.md)?"];
  rehome [label="split the surface, or move the\nsubject to its owning directory"];
  over [shape=diamond, label="verdict over\n(above docs.size_ceiling, 10000)?"];
  limit [shape=diamond, label="verdict allowance\n(above docs.size_limit, 6500)?"];
  crit [shape=diamond, label="is a criterion\ntrue of this file?"];
  goal [shape=diamond, label="verdict allowed\n(above docs.size_goal, 5000) with an\nobvious section boundary?"];
  split [label="split into docs/ siblings\n(references/splitting.md)"];
  nocrit [label="no criterion holds: length alone\nis not one, and neither is\npreferring not to split — split"];
  mark [label="mark the allowance or exemption\nunder the title (for size-exempt,\nverify the parsing consumer first)"];
  rows [shape=diamond, label="routing rows above\ndocs.max_index_rows (20)?"];
  group [label="introduce an\nintermediate grouping"];
  links [label="repair citations: convert bare paths,\nfix dead targets and stale anchors,\nrelink restating anchors"];
  moved [shape=diamond, label="did this change create a directory\nor move a section body?"];
  sweep [label="run the three sweeps, then run\nthem again after the repairs"];
  recheck [label="re-run measure.sh"];
  resolved [shape=diamond, label="every finding repaired, or\ndismissed with a stated reason?"];
  done [shape=doublecircle, label="findings resolved\nor dismissed"];

  start -> scope -> measure -> subjects;
  subjects -> rehome [label=" no"];
  rehome -> over;
  subjects -> over [label=" yes"];
  over -> split [label=" yes"];
  over -> limit [label=" no"];
  limit -> crit [label=" yes"];
  limit -> goal [label=" no"];
  crit -> mark [label=" yes"];
  crit -> nocrit [label=" no"];
  nocrit -> split;
  goal -> split [label=" yes"];
  goal -> rows [label=" no"];
  split -> rows;
  mark -> rows;
  rows -> group [label=" yes"];
  group -> links;
  rows -> links [label=" no"];
  links -> moved;
  moved -> sweep [label=" yes"];
  moved -> recheck [label=" no"];
  sweep -> recheck;
  recheck -> resolved;
  resolved -> over [label=" no"];
  resolved -> done [label=" yes"];
}