Documentation system
Docs are run, not written; the library documents itself queryably; plans record what shipped; no site, no generated reference.
3 Strong · 6 Solid · 2 Partial · 1 Emerging
Measured against: Sphinx · rustdoc · MkDocs · literate programming · Folders: base/doc(opens in a new tab) · base/meta(opens in a new tab) · base/reflect(opens in a new tab) · For programmers: this area's reference
Rethought from first principles
What Softanza kept from what works, and what it rethought, as the library wrote it down in its design documents and narrations.
The Softanza wayDocumentation is run, not just written: every example shows real output, and the library can explain itself from its own source.
Kept from the best practice
- Several doors for several readers: one-liners for the hurried, narrations for story lovers, references for structured lookup, deep dives for engineers, and FAQs. source(opens in a new tab)
- Plain markdown files kept with the code and hosted on GitHub, so the documentation stays lightweight and accessible. source(opens in a new tab)
- Each method is described where it lives, in a comment in the source, and section headers group methods by capability. source(opens in a new tab)
Rethought
- Narrations explain an idea as a story with real code. Every output block is the actual output of a run, and a guard keeps it true. source(opens in a new tab)
- A chapter stores no output. Each cell promises what it prints, all cells run in a fresh process, and a wrong promise is caught, not hidden. source(opens in a new tab)
- Ask the library in plain words and it answers from its own source comments, with no large language model, because the knowledge already lives there. source(opens in a new tab)
- Because method names follow a grammar, HowTo composes a name from your intent and checks it against the real methods, falling back to search by meaning. source(opens in a new tab)
Documentation is not a module in Softanza; it is a discipline built into how the library is made, and its signature is that the docs are run, not written, and the library can document itself. 134 literate narrations teach through stories whose every code-and-output block is produced by a real executed demo; the library answers Ask() / HowTo() / ExplainMethod() about its own API deterministically; 2,956 files carry inline #--> promises a harness checks; ~63 plans-of-record record what actually shipped. Where it is thin: no published doc site, no generated API reference, no measured coverage, and its own overview has drifted behind the system it describes.
What a crafter does with it, and what stands out
- The docs are run, not written: 134 narrations whose every block is produced by an executed demo
- The library documents itself: Ask() / HowTo() / ExplainMethod() are deterministic and zero-hallucination
- Design docs that record what actually shipped, not just what was intended
- Self-illustrating figures drawn by the thing being documented
What is owed
- A published doc site (MkDocs / Docusaurus over the existing markdown)
- Generate the API reference from the stzReflectFuncs harvester
- Refresh the system overview (5 pillars vs 9 surfaces) and widen the self-doc corpus beyond 2 classes
- Measured doc coverage, and docs wired into CI
The Softanza way, run
What Softanza does differently in this area, shown by code taken from its narrations and guards, and run for this page.
Asked in plain words how to remove duplicates, the library composes the method name from its own naming grammar, and says so.
oDoc = StzSelfDocQ("stzList")
? oDoc.HowTo("remove duplicates")
? oDoc.HasMethod("DuplicatesRemoved")Q([...]).RemoveDuplicates() -- composed by grammar (remove duplicates) 1
run on 2026-10-01 21:18 inside the library at commit 0e72e2e2c; taken from base/education/program/courses/elementary-introduction/chapters/13-the-gap-question.en.md(opens in a new tab)
The library explains a method from its own source comment, and plainly refuses a method that does not exist instead of inventing one.
oDoc = StzSelfDocQ("stzList")
? StzLeft( oDoc.ExplainMethod("DuplicatesRemoved"), 20 )
? oDoc.ExplainMethod("NoSuchThing")DuplicatesRemoved -- No method 'NoSuchThing' in stzList.
run on 2026-10-01 21:18 inside the library at commit 0e72e2e2c; taken from base/education/program/courses/elementary-introduction/chapters/13-the-gap-question.en.md(opens in a new tab)
The lanes, one by one
Lanes and their notes are quoted as they were read at the source, on Read from the source on 2026-09-17, from a read-only main worktree -- base/doc/narrations (134), base/meta/stzSelfDoc + stzLibDoc, base/reflect/stzReflectFuncs, base/meta/promises.py over 2,956 #--> files, base/doc/design (44) + SOFTANZA_*_PLAN.md, and stz-doc-system-overview.md.