DNA: updated from how-this-manual-is-built.md
Root ·
Updated from docs/dna/how-this-manual-is-built.md in the Knowen repository: How Knowen works is kept with the code.
Changes to the content
# How this manual is built **The files.** Each page is a Markdown file in `docs/dna`, with front matter: `key`, `title`, `parents` (all equal), `kind` (overview, concept, technical or guide), a one-sentence `summary`, `order` among its siblings, and `covers`, the code it describes. Pages link each other with `[text](dna:key)` and show images with ``. A page that moves or goes is listed in `docs/dna/_moved.yml`. **Sync on deploy.** Every deploy runs `bin/rails dna:sync` as Root (`Dna::Sync`). It creates new pages first, then renders and updates every page: links become node links, images get a version in their address so readers always see the current one, and each page ends with its generated navigation (Read on, Under the hood, Step by step, and Part of when it has several parents). A page whose file is gone is retired: its open Talk topics and anything readers added under it go to its successor, and its address redirects. Changes are recorded as Root's versions, so every page has a history like any other node. **Diagrams from code.** Each diagram is a short Ruby file in `docs/dna/media/src`, placing nodes, spaces and edges in the style of the graph view, with frames to step through (`Dna::Diagram`). `bin/rails dna:diagrams` draws them as SVG; several frames play as an animation, with no scripts. **Screenshots from demo data.** `bin/rails dna:screens` builds its own database with the demo people, graphs and proposals (`db/seeds/development/manual.seeds.rb`), starts the app on it, and walks headless Chrome through the entries of `docs/dna/media/screens.yml`: pictures become WebP, sequences of frames become GIFs. Your own data is never used, so the pictures show the same story every time. **Checks.** `bin/rails dna:lint` (`Dna::Lint`) applies the rules of [Writing this manual](dna:writing-this-manual/nodes/29579), and the test suite runs it on every pull request: too many children, a guide without a picture, a missing summary, a broken link, an image without a caption, a diagram out of date with its source, or a `covers` path that names no file fail the build. `bin/rails dna:check` (`Dna::Check`, no database) runs on every pull request too: it compares the branch with its base, and for each changed file that pages cover, wants one of those pages changed. It names the screenshots on those pages to retake, and warns about user-facing code (controllers, views, helpers, policies, services, models, serializers, scripts and routes) that no page covers yet. # 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.
