DNA: updated from writing-this-manual.md

Root ·

Updated from docs/dna/writing-this-manual.md in the Knowen repository: How Knowen works is kept with the code.

Changes to the content

# Writing this manual

**The rules.** They come from the explanation-graph method used to build graphs from many sources (see [Growing a graph from many sources](dna:growing-from-sources/nodes/29550)).
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](dna:how-this-manual-is-built/nodes/29552) explains the files and the tools; the `knowen-dna` skill in the repository lists the same steps for agents.

# Parents

* This manual is a Knowen graph

Feedback00

No feedback yet. Say whether this change improves the node.

Sign in to add a new comment.