Writing this manual

Public graph

Created about 4 hours ago, updated about 4 hours ago · Owners: Root

ID29579

The rules. They come from the explanation-graph method used to build graphs from many sources (see Growing a graph from many sources).

  1. One idea per page, self-contained. Write the page, then decide what it needs.
  2. Direction: a parent's explanation needs its children.
  3. At most five children. When a sixth is needed, add a theme page that groups them.
  4. Several parents where they are real. All parents are equal, and a page is listed under each. At least 15% of pages have more than one parent.
  5. Layers by kind: overview and concept pages tell the story; technical pages explain how it is built; guide pages are step by step and are leaves.
  6. Shapes: a concept says what it is, why it matters, how it works, how it is built, and its limits, in 120 to 400 words (a closing References list does not count). A guide gives the goal, numbered steps with screenshots, what happens next, and how to undo.
  7. Pictures: every mechanism gets a diagram, every merge or publishing idea an animation, every guide a screenshot, and every image a caption. Screenshots come from the demo data, never from real accounts.
  8. Honest labels: what is not built says "In development".
  9. Links between pages use [text](dna:key).

In step with the code. Every change to what people or agents see or can do updates the pages that describe it, in the same pull request. Each page lists the code it describes in its front matter (covers:). bin/rails dna:check BASE=<branch> names the pages a change affects and fails when none of them changed; a change that alters nothing visible says so with a commit line Manual: unaffected (why).

Changing a page. Edit the file in the same pull request as the code it describes. Redraw the diagrams (bin/rails dna:diagrams) and retake the screenshots (bin/rails dna:screens) that the change affects, run bin/rails dna:lint and bin/rails dna:check, look at the page in the app at desktop and phone width, and open the pull request. How this manual is built explains the files and the tools; the knowen-dna skill in the repository lists the same steps for agents.

See in the graph Search below

Parents1More general nodes this one belongs to