Deep Technical Articles From a Codebase
The failure mode of generated technical writing is confident fiction:
plausible code that never existed, outputs that never ran. This process
makes fiction structurally hard.
Article types (per repo)
- ARCHITECTURE — module-by-module walkthrough. Quote real code.
- COOKBOOK — recipes; every command executed, output pasted verbatim.
- DECISIONS — ADRs as stories: context → options → decision → consequences.
- COMPETITIVE — landscape with dated evidence and honest kill criteria.
The writing protocol
- Read the source first. Never describe a module you have not opened.
Cite symbols by name; an architecture piece should reference ≥5 real ones.
- Excerpts are verbatim, with provenance. Copy from the file, keep the
file path next to the block. If you elide, mark
... explicitly. After
writing, programmatically re-verify excerpts against source (substring
match after whitespace normalization).
- Commands are executed, not imagined. Build fixtures in temp dirs,
run the real CLI, paste the real output (trim long runs, never invent
fields). If a command fails, that is content: fix the doc to match
reality or record the failure as a finding.
- Numbers come from runners: test counts from
npm test output, package
sizes from npm pack --dry-run, dates from git log. Recompute totals;
one observed table didn't sum to its own claimed total.
- Diagrams earn their place: one per major flow, ≤20 nodes, every
diagram gets a numbered caption and a following paragraph saying what to
notice. Mermaid with quoted labels; ASCII for decision forks.
- Bilingual split: prose in the audience language; code, commands,
output, error messages verbatim in original.
- Fact-check pass (mandatory, separate from writing): verify every
excerpt, re-run cheap commands, check test counts and versions. Our own
review waves found: a fabricated JSON output block, a quote with a dropped
code flag plus an invented paragraph justifying the mistake, and stale
bug states. Assume your first draft contains these too.
- Stale-content sweep: if the code changed since writing (git log),
update excerpts and claims — especially "open bug" narratives that were
since fixed.
Polish rules
导语 (2–4 sentences: why this matters) and 结语 (takeaways) on every major
piece. Unified terminology per family. No shortening during polish — better
flow, more depth, not less content.
1---2name: deep-tech-article3description: Produces verified deep-dive technical articles from a codebase: architecture walkthroughs quoting real source, cookbooks whose every command was actually executed, ADR-style decision stories, and competitive analyses — with diagrams and bilingual output. Use when turning a repository into publishable blog content, documentation, or launch material. Enforces the fact-check protocol that caught 30+ errors in our own first drafts.4license: MIT5---67# Deep Technical Articles From a Codebase89The failure mode of generated technical writing is confident fiction:10plausible code that never existed, outputs that never ran. This process11makes fiction structurally hard.1213## Article types (per repo)14151. **ARCHITECTURE** — module-by-module walkthrough. Quote real code.162. **COOKBOOK** — recipes; every command executed, output pasted verbatim.173. **DECISIONS** — ADRs as stories: context → options → decision → consequences.184. **COMPETITIVE** — landscape with dated evidence and honest kill criteria.1920## The writing protocol21221. **Read the source first.** Never describe a module you have not opened.23 Cite symbols by name; an architecture piece should reference ≥5 real ones.242. **Excerpts are verbatim, with provenance.** Copy from the file, keep the25 file path next to the block. If you elide, mark `...` explicitly. After26 writing, programmatically re-verify excerpts against source (substring27 match after whitespace normalization).283. **Commands are executed, not imagined.** Build fixtures in temp dirs,29 run the real CLI, paste the real output (trim long runs, never invent30 fields). If a command fails, that is content: fix the doc to match31 reality or record the failure as a finding.324. **Numbers come from runners**: test counts from `npm test` output, package33 sizes from `npm pack --dry-run`, dates from git log. Recompute totals;34 one observed table didn't sum to its own claimed total.355. **Diagrams earn their place**: one per major flow, ≤20 nodes, every36 diagram gets a numbered caption and a following paragraph saying what to37 notice. Mermaid with quoted labels; ASCII for decision forks.386. **Bilingual split**: prose in the audience language; code, commands,39 output, error messages verbatim in original.407. **Fact-check pass (mandatory, separate from writing)**: verify every41 excerpt, re-run cheap commands, check test counts and versions. Our own42 review waves found: a fabricated JSON output block, a quote with a dropped43 code flag *plus an invented paragraph justifying the mistake*, and stale44 bug states. Assume your first draft contains these too.458. **Stale-content sweep**: if the code changed since writing (git log),46 update excerpts and claims — especially "open bug" narratives that were47 since fixed.4849## Polish rules5051导语 (2–4 sentences: why this matters) and 结语 (takeaways) on every major52piece. Unified terminology per family. No shortening during polish — better53flow, more depth, not less content.
zhengqiuyang