Doc system test
Research report · 18 Nov 2026 (Pacific)

The old CyanPrint, documented in our new documentation system

What this is
The old CyanPrint docs, rewritten in our new documentation system and shown here as rich pages, with three short pages on what the old docs got wrong and what we learned.
Why it exists
Can the new documentation system explain a complicated product correctly, and how should the docs for it be organised?
Length
6 short pages; the last one is where you decide.
The situation

We tested the new documentation system on a real, complicated product

We have designed a new way to write our docs. Each doc gets a short header, precise words, worked examples and a fixed place in a folder tree. A design on paper proves little, so we tried it on real code.

We picked the old CyanPrint, also called sulfone. CyanPrint builds project folders for you. Each recipe it runs is a template: a package that asks a few questions, then writes files. The folder it writes into is the target folder, such as a new project on your machine.

CyanPrint is a good test because it is hard. Its code spans eight repositories, in Rust, Go, C# and TypeScript. Templates depend on other templates, share one folder, and merge with your own edits.

It also has an old documentation site, called silicon: about 128 pages. So we could check the old docs against the code, and write new ones.

What this site is

This site is the CyanPrint docs themselves, rendered as rich pages

The first version of this test was a report about the docs. The feedback was clear: show the docs themselves, with diagrams, interactive pieces and the word overlay. So the Docs section of this site is now the docs tree itself.

Every doc is one page. Maps at each folder let you go from the whole product, to one area, to one doc. Each doc opens with a short header: its type, area, code paths and related docs.

Words with a dotted underline come from the product's word lists. Hover or tap one to see its meaning; click for the details and the words not to confuse it with.

Rich docs can use five pieces: diagrams, file trees before and after, steppers that walk an algorithm one step at a time, walk-throughs of the real code, and tables. Here is where this early version stands:

1
second-round doc live so far: client-side state and determinism
79
first-round docs, kept under round-1 until each is replaced
Measured

A second round is rewriting every doc in this style, with the real reasons and many more concepts. Its docs land here batch by batch. The first one is the centre of the design: everything about a project lives in its own folder, so every template run must be repeatable.

What we found

The system carried the product, and the old docs were mostly wrong

The documentation system works for a product this complicated. 77 of 79 concepts found a place in the tree without a fight.

The product split into six bounded contexts: areas that each have their own words, such as the registry that stores published templates. Each matches one repository or one part of one.

The old docs were not just out of date. Of 62 checked findings, 35 say something the code does not do Measured. Here "measured" means read from the code and counted; nothing was run. Two security-related findings are kept out of this site on purpose.

The map

Three short pages frame the docs, then the docs speak for themselves

The pages follow one story. Here it is in short:

The story in short
  1. We tested our new documentation system on a real, complicated product - the old CyanPrint, a tool that builds project folders from templates.
  2. We read its code, wrote its docs in the new system, and checked the old docs (called silicon) against the code.
  3. The code has 79 concepts; the old docs covered 16 correctly, 5 partly, 28 wrongly and 30 not at all.
  4. Of 62 checked findings, 35 say something the code does not do and 21 leave out something a reader needs.
  5. The new system carried the product - 77 of 79 concepts found a home - and nine changes to it were accepted.
  6. This site shows the docs themselves - maps, meta blocks, the word overlay, diagrams, steppers and real code.
  7. A second round is rewriting every doc with the real reasons and more concepts; its docs land here batch by batch.
  8. One question is open - what to call the folder that holds the areas.

The site is in this order:

  1. Concept map: every concept, and how well the old docs covered it.
  2. Old docs: what silicon got wrong, side by side with the code.
  3. The docs: the CyanPrint docs themselves, in the new system.
  4. Verdict: what fit, what changed, and where the folders felt forced.
  5. Decide: the one open question.