book-technical
Technical book craft reference: concept gradient, running project, failure-first teaching, code standards, diagrams, exercises, version handling, the technical-book AI tells. Read by all agents on programming, engineering, and data science books.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- book-technical
- description
- Technical book craft reference: concept gradient, running project, failure-first teaching, code standards, diagrams, exercises, version handling, the technical-book AI tells. Read by all agents on programming, engineering, and data science books.
03 SKILL.md 正文
Technical
The reader of a technical book is trying to become someone who can do the thing. Every chapter must move them closer to doing it themselves, and the surest sign of a book that fails is a reader who can follow along but cannot deviate.
Structure
Default: Intro (10-15%) → Foundations (25%) → Practice (30%) → Advanced (20%) → Reference (10%). Within that:
- Running project. The reader builds one thing across the book. Each chapter adds a capability. By the end they have something that works and that they understand every line of. Books without a running project produce readers who have read about the thing.
- Concept gradient: each concept is introduced once, at the first chapter that needs it, with the minimum needed then, and deepened later where it becomes necessary. The outline's dependency DAG enforces this; the architect verifies there are no forward references.
- Difficulty is monotonic non-decreasing within a part; the first chapter of a part can step back slightly.
- Reference material (API tables, option lists) goes to the back or an appendix, never inside a teaching chapter.
Failure-first teaching
The single largest gap between AI technical writing and good human technical writing: humans show the thing going wrong.
- Show the naive version first. Run it. Show the actual error message or wrong output.
- Explain why it fails in terms of the mental model, not just the fix.
- Then the correct version. Then what else would have broken it.
- Debugging is a chapter topic, not an afterthought. How would the reader know something is wrong? What would they look at first?
- Performance, security, and edge cases appear where the reader would first hit them, not in a separate "advanced considerations" chapter.
Code standards
- Every code block has a language tag and, when it is a file, a filename comment on line 1.
- Runnable, or explicitly labeled
# pseudocode. Imports included. Expected output shown after. - Lengths: 10-30 lines when introducing; 30-80 when building; 80+ only for a complete listing, and then with the key section explained separately.
- Version pinned in
PRD.mdand stated once in the introduction; not repeated per chapter. Breaking changes and security-relevant versions are called out inline. - Prefer "save the file" to "click File → Save"; UI paths change, concepts do not.
- The fact-checker runs code blocks where the environment allows. Write code that can be run.
- Diagrams: Mermaid for flow/sequence, ASCII fallback for EPUB readers that do not render Mermaid, tables for comparisons. At most three per chapter.
Chapter design
- Hook: a concrete task or a concrete failure the reader recognizes
- Concept: minimum needed now, linked to what they already know from earlier chapters
- Build: add to the running project; show the code, run it, show the output
- Break: what goes wrong when the reader deviates; show it
- Explain: the model behind the fix
- Exercise: one thing the reader does without the book's hand (three levels: guided, hinted, goal-only)
- Exit: what the next capability is and why the current build needs it. Not a summary.
Technical-book tells
- Every chapter starts with "In this chapter, you will learn."
- Code that always works on the first try.
- Explanations that restate the code line by line without adding a model.
- "It is important to note that" before every caveat.
- Bullet lists of "best practices" with no reasoning.
- Diagrams of boxes and arrows that add nothing to the prose.
- Exercises that repeat the chapter's example with a variable renamed.
- A "conclusion" section per chapter.
- Uniform confidence about tradeoffs that are genuinely contested.
- Analogies for concepts that are simpler than the analogy.
Language notes
- Korean technical books: 개발자 독자는 영문 용어 병기를 기대한다 (예: 컨텍스트 윈도(context window)). 첫 등장 시 병기, 이후 한글 또는 원어 중 STYLE.md에서 정한 쪽. 코드 주석은 영문 또는 한글 중 하나로 통일. 경어체(합니다체) 또는 평서체(한다체) 하나로 고정.
- English: second person, present tense, active voice. "You" is the reader; "we" only if the fingerprint allows.
- Japanese: です・ます体 for tutorials; だ・である体 for reference sections; do not mix within a chapter.
Validation (architect scoring for technical)
DAG has no cycles and no forward references; running project defined and advanced in every practice chapter; failure shown in every build chapter; difficulty monotonic within parts; exercise per chapter with three levels; versions pinned; reference material segregated; diagrams ≤ 3/chapter and each does work the prose cannot.
Visuals
Diagrams are code (Mermaid, D2, Graphviz, SVG), versioned in visuals/figures/src/, rendered to SVG for EPUB and PNG for print, with a single theme file for fonts and color roles. Architecture, sequence, state, and data-flow diagrams use the same node and edge grammar throughout (art bible figure system). Screenshots are real and cropped to the relevant region, annotated in SVG overlays, and dated in the caption if the UI may change. Terminal output is a code block, never an image. Charts from measured data with units. ≤ 3 figures per chapter; each does work the prose cannot. figure-engineer produces; fact-checker verifies every label against the text and the running project's actual state.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.