Bluebook Writing

Bluebook Writing is a repeatable method for explaining why a system is designed the way it is. It pairs an everyday story containing no technical terms with a professional explanation of mechanisms, boundaries and costs. The aim is design reading: helping readers understand architectural choices through concrete situations.

The method begins by choosing one familiar scenario, such as a repair crew, workshop or kitchen. Every technical term receives a fixed everyday equivalent in a shared table. New analogies must describe something familiar from daily life, be expressible in one word and be registered in that table. Once established, the wording stays consistent throughout the book or course.

The opening part of each section, N.1, tells the design point as a scene from that scenario. A technical term entering the scene calls for rewriting the sentence rather than adding a glossary explanation. N.2 then adds formal names, mechanisms, applicable boundaries and costs. It must contribute information the everyday story cannot carry instead of repeating it with technical labels. Official quotations belong in this professional layer.

Use this skill when explaining unfamiliar architectures, frameworks or open-source projects to people who do not write code. It also fits books, long-form articles and internal architecture documents focused on design rationale, especially when one real-world story must hold the argument together.

It can help repair drafts dominated by terminology, filler or abstractions without concrete examples. For API references and task-based documentation centered on procedure, use technical-writer. The method does not replace environment-specific validation, testing or expert review. Clarify the target system, audience and section scope before proceeding if any is missing.

Start with the system to explain, the intended audience and the section's design point. The resulting section combines the plain story and professional layer with three closing elements. N.3 is a glossary mapping everyday sayings to newly introduced professional terms; small sections may omit it. N.4 gives two to four misconceptions, stating each wrong understanding before the correction. N.5 provides one or two self-check actions readers can apply to their own projects, so the section ends with a practical transfer point.

The writing limits call for 1,400-2,200 Chinese characters and two to four diagrams per section. Bold and em-dashes are each limited to two per thousand characters. Second-person address is limited to four instances per section, ideally none. Paragraphs contain two to six sentences, alternating long and short sentences. Remove stock filler such as "in conclusion" and "it is worth noting," along with unsupported promotional adjectives.

A terminology firewall keeps package names, file paths, code and raw statistics in an appendix. Deleting package names from a paragraph provides a diagnostic: if an argument remains, it explains design; if nothing remains, rewrite the code walkthrough. Titles normally ask a question containing a concrete object, number or action. A declarative title is reserved for a sufficiently counterintuitive statement. Each diagram needs a conclusion-style caption and a paragraph connecting it to the argument.

The skill supports writers explaining systems to non-programmers and authors developing design-focused books, courses or internal architecture documents. Its checks target recurring failures: technical vocabulary leaking into the plain story, a professional layer that adds no information, and an analogy system drifting into unrelated metaphors. Changing an established analogy requires deliberate registration and revision of earlier chapters. When security topics arise, keep findings and boundaries explicit and avoid unverifiable statistics.