| name | engineering-writing |
| description | Writing engineering essays, position papers, technical blog posts, and architecture memos intended for external or semi-external readers. Use when drafting or revising long-form argumentative prose — Notion position papers, public blog posts, shared design docs meant to persuade, RFCs with argumentative structure. Provides structural patterns (lead with position, justify after), section-heading heuristics (sentence case, specific, opinionated), an AI-voice-tells checklist (cadence uniformity, reveal- signposting, contrast sentences and rule of three, vocabulary, heading patterns), and a revision workflow. Skip for task specs (use create-task), rule files (use create-rule), code comments, or short internal-only docs. |
| user-invocable | true |
Engineering Writing
Guide for writing long-form engineering prose that reads like a person wrote it, reaches a confident position, and earns the reader's continued attention.
When to use
- Position papers and RFCs meant for semi-external readers (Notion papers, shared design docs)
- Engineering blog posts
- Architecture memos arguing for a specific approach
- Long-form ADRs with argumentative structure
Skip for: task specs, rule files, code comments, short internal-only docs (a few paragraphs don't warrant this apparatus).
If the artifact's function is to get a decision from the principal (an RFC or ADR opened in order to approve, reject, or redirect), this skill governs the body but NOT the opening — see §Decision artifacts lead with the decision below before applying the stakes-first pattern.
Structure serves content, not the other way around
This is the most common way essays go wrong: the writer picks up a structure that worked for some other essay — often a sibling piece in the same corpus — and applies it section by section to different content. The content doesn't fit. Sections get forced. Claims get invented to fill slots. The resulting essay is structurally correct and rhetorically hollow.
The skill's structural advice below is an inventory of moves, not a required sequence. A given essay might use six moves, or ten, or three. The moves you use should be the ones your content demands.
Signs your structure is driving your content instead of the reverse:
- A section whose central claim is a stretch. If the best you can do for "three ways this goes wrong" is three paraphrases of the same concern, there aren't three ways — you're padding.
- A named taxonomy with forced distinctions. If your "four camps" collapse pairwise into each other on inspection, you have two camps, not four. Don't round up.
- A "named contribution" whose name has no load. If your scheme is called "the X model" and nothing about it is meaningfully an X, the name is imitative. Describe what it is instead.
- Forward-referenced claims that never come back. If your exordium promises "a framework, a landscape, a named pattern, and a roadmap," and three of those four are thin, you don't need four sections.
- Phases or layers padded to match an exemplar. Real phases correspond to real decision points or external gates. Invented phases correspond to slots in a template.
Check: for each section, ask "if I deleted this, what argumentative move would I lose?" If the answer is "stylistic parallelism with the other post" or "I don't know," cut it.
Copy patterns only when your content has the same shape. The sibling post's "GitHub is the outlier" works because GitHub literally is the outlier in the forge-signing landscape. "Four questions, not one" works because there are literally four orthogonal design dimensions. Before reusing either structural move, check: does your content have an outlier? Four orthogonal dimensions? If not, you're cargo-culting shape.
Dan Luu: "Copying someone else's style is unlikely to work for you." Start from what your content needs.
Structural pattern: stakes before position, then justify
The right structure depends on whether you're writing informative prose (reader already cares) or persuasive prose (reader needs to be brought along).
Informative prose uses the inverted pyramid — conclusion first, details after. This is journalism's structure. Works when readers are searching for facts and will stop reading whenever they have enough.
Persuasive prose uses the classical rhetoric structure — exordium, narratio, propositio, confirmatio, peroratio. Hook, stakes, thesis, argument, conclusion. The thesis comes after stakes, not before, because readers need to feel the problem before they can receive the position as reasonable rather than overreach.
Position papers are persuasion, not journalism. If your thesis is counter-intuitive ("this thing that seems minor is actually load-bearing"), leading with it makes readers dismiss it. Leading with stakes gets them to say "oh, this is a real problem" before you tell them what to do about it.
Inventory of moves engineering essays draw on. A given essay uses some subset, in an order that serves its argument:
- Hook / observation. One or two paragraphs. Concrete, not abstract. May hint at the thesis without planting the flag. ("This paper is about ... a design pattern we think handles the problem.")
- Why it matters. Stakes, context, what changed. This is the load-bearing section for making the reader care. Skeptical reader leaves here if you haven't earned their attention.
- What you think. Your position, plainly stated, now that stakes have landed. Keep it tight (3-5 paragraphs). Invite disagreement: "if you buy this, the rest is the argument for how to act on it; if you don't, the rest is the argument for why you should."
- The conceptual move. The framework or distinction that unlocks clean thinking about the problem. Often the thing that makes your position defensible.
- Landscape and evidence. What others do, how the camps differ, what the forge/tool/standard actually provides.
- Your contribution (named). The design pattern, architectural move, or principle you're offering. Give it a name.
- Validation. Threat models, security analysis, stress-testing the contribution against known failure modes.
- Case study. What the framework reveals when applied to a real system — usually your own. Grounding before prescription.
- Prescription / roadmap. Phased progression from messy state to principled one. Structural phases and activation gates, not timelines.
- Open questions and gates. What you don't know, what would change your mind.
- Advice for readers in a similar place. Short, practical, drawn from your investigation without being autobiography.
- Further reading. Citations.
Where to bury what:
- Don't bury the position in section 8 of 12. Readers who stopped reading won't find it.
- Don't put the position in section 1 either, for a counter-intuitive thesis. Readers dismiss it without context.
- Section 3 (right after stakes) is the sweet spot for persuasive thesis placement.
- Very skimmable-first readers who want the thesis upfront can see the hint in the exordium and skip to the position if they want.
Decision artifacts lead with the decision
Everything above governs prose whose job is to persuade a reader who is free to walk away. It does not govern an artifact whose job is to get a decision from someone with the authority to make it. When an RFC or ADR is the surface a principal opens in order to decide, they are not being brought along — they are approving, rejecting, or redirecting on scarce attention, and burying the call behind stakes forces them to do the compression themselves.
For those artifacts a decision-grade summary sits ABOVE the structure on this page: the call in one bolded directive sentence, three to five one-line consequences, and an explicit "accepting this = agreeing with the call." The stakes-first body then follows unchanged, for the reader who wants the reasoning.
The two compose rather than conflict. Stakes-first governs where the argument begins; the summary block governs where the decision is legible. A reader who wants persuading reads past the block into the body exactly as prescribed above.
This reconciliation is load-bearing. Without it the two sets of instructions contradict, and this page wins silently because it is the more specific writing advice — which is exactly what happened on 2026-07-21 and again on 2026-07-22, when RFCs serving as decision surfaces were published stakes-first and the principal bounced both ("way too long... not decisionable"). The required block shapes live in /draft-rfc step 7 and /draft-adr step 5.
Handling forward references in the position section
A common trap: your position section references concepts that haven't been introduced yet — "we stay Camp 3.5," "the four dimensions stay decoupled," "the capabilities model is load-bearing." If the position comes before the framework/landscape sections that introduce those concepts, readers are lost.
Two patterns that work:
- Slim the early position to just the claims that stand alone. Distribute the context-dependent claims into the sections that set them up. The Camp 3.5 shorthand lands at the end of the landscape section. The "decoupling as code discipline" claim lands at the end of the framework section. The "capabilities-model sovereignty" claim lands in the contribution section.
- Forward-promise in the exordium. "The rest of the paper elaborates these into a framework, a landscape, a named design pattern, and a roadmap." Tells the reader what's coming without demanding they understand it yet.
Use the distribution pattern when the position has claims that are meaningfully different in nature (values vs design principles vs shorthand labels). Use the forward-promise when the position is coherent but context-heavy.
Writing for external readers
Position papers often draw on internal material: task IDs, commit SHAs, specific timelines, internal review threads, project-specific terminology. Most of this is noise to external readers and undercuts the paper. Strip it.
What to strip
- Internal ticket or task IDs in the main body (mt#XXX, PROJ-123). Readers can't verify these, can't use them, and they read as advertorial for your internal tracker. Translate to descriptive summaries ("a tool-name typo in a skill file" beats "mt#1030 via the pre-tool hook"). If the IDs are genuinely useful for team execution, publish them in a separate team-facing doc and link from the paper.
- Hard timelines in roadmap sections, especially when your position is "progress is gate-driven, not timeline-driven." Timelines contradict the gates argument. Pick one. If phases activate on triggers rather than calendar, the timelines undermine your own case.
- Internal file paths, branch names, repo-specific conventions unless the paper is explicitly about them.
- Dense internal context the reader can't verify or use. ("mt#834 was superseded by mt#847 before mt#846 was merged.") This reads as chronology, not analysis.
What to keep
- Named systems and tools that carry information for external readers (Dependabot, Renovate, SLSA, Fulcio).
- Concrete verbatim quotes from primary sources.
- Specific attack case studies and incidents by name when they anchor a claim.
- One or two internal examples as illustration, if they ground an abstract point. Frame them as "an example from a system we've been working on," not as the center of the argument.
Roadmap structure: pattern vs specifics
A roadmap in a position paper serves two audiences at once:
- Your team, which wants a plan it can execute against tickets
- External readers, who want a phased-maturity pattern they can adapt
Both get served, but not with the same content. When writing for external readers, describe each phase by its structural purpose (foundational hygiene, attribution correctness, identity-model decision, cryptographic provenance, etc.), not by the specific tickets that implement it. Describe gates (what triggers the phase) rather than timelines (when it happens). If you need the team-facing version with task IDs and dates, publish it separately and link from the paper.
Case study placement: grounding before prescription
A case study ("here's what the framework reveals when applied to a real system") usually belongs before the prescriptive roadmap, not after. Readers absorb the concrete example as grounding for the abstract prescription. If the roadmap comes first, readers have no anchor for what each phase is addressing; the phases read as abstract tidying.
Default order: frame → contribution → validation → case study → prescription.
Exception: if the case study is very short or very abstract, it can work as a closing illustration. But that's the exception.
Threat analysis: before the design pattern, not after
If your paper proposes a design pattern and also analyzes threats the pattern has to handle, put the threat analysis before the design pattern, not after. Threats-first motivates the design requirements. Threats-last reads as post-hoc justification.
Reader experience with threats-first: "Here's what breaks. Here's why any design has to handle X, Y, Z. Here's our design, which handles them like this." Natural evaluation.
Reader experience with threats-last: "Here's our design (abstract). Now let me convince you it's good by showing you threats it handles." The design lands without criteria; the reader is stuck trusting you until the threats arrive.
The exception: if the design pattern is truly the main event and threats are a minor validation aside, threats-last can work. But for papers where the threats are load-bearing for the design, threats come first.
Phases and gates: integrate, don't separate
When a roadmap has phases AND each phase has an activation trigger ("gate"), resist the urge to split them into two sections (Phases then Gates). Readers end up cross-referencing. Each phase should describe what it is AND when it activates in one place.
Good:
### Phase 2. Bot-identity architecture decision
*What:* Choose your bot-identity model explicitly.
*Activates:* When Phase 1 produces operational data showing where gaps hurt.
Bad:
### Phase 2. Bot-identity architecture decision
Choose your bot-identity model explicitly.
### Gates
Phase 2: activates when Phase 1 produces operational data showing where gaps hurt.
Phase 3: activates when ...
The "bad" version forces the reader to hold each phase in memory while they scan for its gate. The "good" version delivers both facts together.
Closing note about gates-overall can remain as a short paragraph after the phases, but the per-phase activation condition belongs with each phase.
Open questions: field-level before internal-level
A "what's still open" section serves two audiences: external readers who want to engage with the field's unresolved questions, and internal readers who want to see where you're uncertain. Lead with the field-level questions. Put the internal stance questions second. Bury the specific-to-your-situation decisions entirely if they don't teach the reader something.
Weak:
- Phase 2 model winner. Depends on our multi-tenancy plans.
- Phase 5 sequencing. Which forge first? Likely whichever a paying customer runs on.
Strong:
- How should agent-authored commits count toward a human's contribution graph? No consensus in the field.
- When will forge ecosystems recognize sigstore as Verified? No single team controls this.
- Choices we've taken that aren't permanent: GitHub App over service-account. Revisited on portability or sovereignty pressure.
Field-level questions invite reader engagement. Internal-only decisions are noise to anyone who doesn't work at your company.
Origin / appendix: advice to future investigators, not autobiography
If you include an origin section ("how this paper came to exist"), frame it as advice for future investigators doing similar work. The external reader doesn't care about your chronology. They do care about patterns they can apply to their own system.
Good origin framing:
- "If you're doing a similar audit..."
- "The questions that surfaced the most ground were..."
- "The bugs that pointed at the architectural problem were of the form..."
Bad origin framing:
- "Pull request #646 showed..." (autobiography)
- "The investigation began when..." (autobiography)
- "We then discovered..." (chronological narrative)
A brief internal anchor ("this paper exists because one such asymmetry led back through several layers of half-explicit commitments") can ground the section. But it shouldn't be the organizing principle. The organizing principle is the advice.
Section heading heuristics
AI-generated prose trends toward abstract, title-cased, formulaic headings. Human engineering prose trends toward sentence-case, specific, and sometimes opinionated headings.
Weak, AI-flavored:
- "The Problem"
- "Key Considerations"
- "Industry Landscape"
- "Why This Matters Now"
- "A Position"
- "Applied: Six Phases of Maturity"
- "Appendix: Origin of This Investigation"
Stronger:
- "What we think" (not "A Position")
- "What changes when agents are the committers" (not "Why This Matters Now")
- "GitHub is the outlier" (not "Forge Landscape")
- "Four questions, not one" (not "Conceptual Framework")
- "A capabilities model" (not "The Forge-Capabilities Model")
- "Three ways this goes wrong" (not "Threat Models and Security Analysis")
- "What the audit of our own code turned up" (not "A Case Study")
- "Where this started" (not "Appendix: Origin")
Rules of thumb:
- Sentence case over title case
- Specific claims over abstract nouns ("GitHub is the outlier" vs "Forge Landscape")
- Verb phrases over noun phrases where natural ("What we think" vs "Our Position")
- Let a heading tease the section's conclusion, not merely name its topic
Named contributions need real distinctness
If you give your design pattern or framework a name ("a capabilities model," "the authority ladder," "the four-dimension audit"), the name has to describe something genuinely distinct. A good name compresses an idea the reader can then recall with one phrase. A bad name is imitative — you gave something a label because a sibling essay did, not because the thing deserves one.
Check: can you define the name in a sentence, and does the definition point to something the essay couldn't have made just as well without the name? If the definition is "three layers resolved by priority" and the name is "a layered capture model," the name is adding nothing. Call it what it is.
Named contributions from other essays in the corpus ("a capabilities model," "Camp 3.5") belong only to the essay that invented them. Don't reuse them in adjacent essays to claim kinship.
AI-voice tells to avoid
Refreshed 2026-07-24. The tell landscape moves fast and splits by model. Recheck it every quarter or so against current sources (vrid.ai, oliviacal.com, huntingthemuse.net, pangram.com, duey.ai; see References) rather than trusting this list forever.
These are the patterns readers pattern-match as AI writing. Individual instances aren't damning; clustering is the tell.
Cadence uniformity is the dominant tell
Rhythm gives away more AI writing than any single word choice, and it's the tell that survives every other fix. A draft can be scrubbed of every banned word below and still read as a model, because the vocabulary pass never touches how the sentences are shaped underneath. Researchers call the human contrast burstiness: natural variation in sentence length and rhythm across a passage. Low burstiness, flat and repeating, is what gives AI prose away going into 2026 — more reliably than any punctuation mark.
Three shapes to check for:
- Sentence-length clustering. Most models default to sentences in the ~18-24 word range and repeat that band paragraph after paragraph. One 20-word sentence followed by another 20-word sentence followed by another is the tell, not any single sentence's length.
- Uniform paragraph length. Paragraphs come out the same size: three or four sentences, every time, instead of some running long and others landing in a single line.
- Paragraph ends on a neat bow. Every paragraph closes with a summary line restating what it just said. Real writing sometimes trails off mid-thought, sometimes lands hard and stops, sometimes just moves on to the next point.
Catch this by reading a section aloud, not by scanning for words. The cadence-and-structure pass in the revision workflow below covers it.
Reveal-signposting
"Here's the part that...", "here's the thing...", "and here's the tell that...", "here's where it gets interesting." Debate-team cadence: it promises a payoff, then delivers an ordinary point. Cut the windup. State the point.
Contrast sentences and rule of three
"This is not X, it's Y" and "not just X, but Y" used to sit lower on this list as minor tics. They've moved up: paired with cadence uniformity, they're one of the fastest patterns a reader's eye catches, and current sources rank them as top-tier. Same for the rule of three: three bullets, three adjectives, three parallel clauses, every section. Either pattern is fine used once; repeated across a piece, it's a signature.
Em dashes: no longer a reliable signal alone
The 2026 landscape splits by model. GPT-5.1 suppresses em dashes in most contexts unless explicitly prompted for them; Claude and Gemini still lean on them. That means em-dash absence doesn't prove human writing anymore: a GPT-5.1 draft can be dash-free and still carry every tell above it. Treat the dash as one weak, model-dependent signal, not the headline check. Cadence and structure carry the real weight now. (One or two dashes per ~2000 words is still fine on its own terms; it just isn't doing detection work either way.)
Vocabulary
Words that flag AI drafting:
delve, leverage, utilize (when use works)crucial, pivotal, significant, key (as evaluative adjectives without specifics)robust, meticulous, comprehensivefoster, bolster, enhance, garnerunderscore, showcasetapestry, interplay, abstract uses of landscaperesonate, alignenduring, testamentparadigm, holistic, synergy
Phrases
Tics to cut:
- "It's worth noting that..."
- "It is important to remember..."
- "At its core..."
- "Fundamentally,..."
- "Ultimately,..."
- "In today's world..."
- "One might argue..."
- "As previously mentioned..."
- "In conclusion..."
Borrowed phrasings from sibling work
Specific idioms that earn their place in the essay that invented them become tells when they appear verbatim in a second essay by the same author. These are not generic AI-voice phrases — they're signature moves, and using them twice signals "I'm imitating a template" rather than "I'm writing."
Typical patterns that become tells when lifted verbatim from a sibling essay:
- Opening-the-counterposition idioms: "A less fashionable corollary," "If you buy it, the rest is our argument for how to act on it; if you don't, the rest is our argument for why you should."
- Forward-promise enumerations: "The rest of the paper elaborates these into a framework, a landscape, a named design pattern, and a roadmap."
- Camp-naming shorthands: "Our stance, with the camps named: Camp 3.5." (Whatever decimal-camp move the first essay invented.)
- Phase/gate macros:
### Phase N. X with fixed-format *What:* … / *Activates:* … sub-lines.
- Second-person advice closers: "If you're doing a similar audit" / "If you're [verb]ing your own [noun]."
If a phrasing was load-bearing in the first essay, write something different that does the same rhetorical work in the second. Reusing voice-of-author patterns (contractions, sentence rhythm, directness) is fine. Reusing specific idioms is not.
Other structural tics
- Symmetric structures. Every camp gets exactly the same four bullets; every phase the same four fields. Real writing has ragged edges.
- Present-participle summary clauses. "..., highlighting its significance" / "..., underscoring its role" / "..., emphasizing the importance of." AI glues these onto sentences to claim significance without earning it.
serves as / marks / features / boasts instead of is. AI avoids copulas.- Bulleted lists where prose flows. AI defaults to bullets; prose is often stronger.
- Callout boxes after every section with a "takeaway." Tutorial-flavored; doesn't belong in a position paper.
- Title-cased headings for everything.
- Curly quotes mixed with straight quotes. Check editor auto-substitution.
Tone tics
- No contractions. Human writing mixes them. Use
don't, won't, it's, we're.
- Flat register start to finish. Real writers shift between analytical, conversational, and direct. Flat neutral register is the clearest AI tell after cadence uniformity.
- Over-qualified statements. "In many cases, it may be the case that..." Cut to
often.
- Weasel attribution. "Observers have noted..." / "Many experts agree..." Name who, or say
we think.
Positive patterns to emulate
Voice
- Use
we or I when stating a position. Don't hide behind passive voice.
- Sound opinionated. A position paper that never commits is an analysis, not a position.
- Acknowledge counterpositions explicitly. "If you disagree, here's what the argument requires" reads more confident than hedging everywhere.
- Use contractions.
We don't think beats We do not think.
Sentence construction
- Default to short sentences. Break long ones with a period.
- Active voice unless there's a reason.
GitHub signs the commit beats The commit is signed by GitHub.
- Concrete nouns beat abstract ones.
commit, token, installation beat artifact, identity, mechanism when the concrete term works.
- Name specific systems, tools, companies, versions. Specificity earns trust.
Evidence
- Link primary sources (docs, RFCs, commits, issue threads). Secondary sources are weaker.
- Quote verbatim when phrasing matters.
- Use concrete examples instead of abstract description.
Dependabot does X, Renovate does Y beats different bots approach this differently.
- Cite attack case studies and incidents by name when they anchor a claim.
Structure
- One idea per paragraph. If a paragraph has three points, split it.
- Short sections beat long ones. A long section that's really two sections should be two sections.
- Tables for comparisons across a shared dimension. Prose for sequential argument.
- Bold key terms on first use when naming something. Don't bold every instance.
Revision workflow
Run these passes after the draft is down. Don't edit while drafting.
- Structure-vs-content pass. For each section, ask: "if I deleted this, what argumentative move would I lose?" If the answer is "stylistic parallelism with another essay" or "I don't know," cut. Especially check for: invented phase counts, forced threat-model trios, camp taxonomies padded past their natural breakpoints, "named contributions" whose names don't compress anything real, case-study sections that aren't case studies.
- Sibling-phrasing pass. If you have an essay in the same corpus that shares vocabulary or structure, re-read both side by side. Any specific idiom that appears in both ("a less fashionable corollary,"
*What:* / *Activates:*, "Our stance, with the camps named") is a tell. Rewrite the second one in different words that do the same rhetorical work.
- Heading pass. Review every heading. Sentence-case. Specific. Opinionated where possible. Rewrite any that match AI-flavored patterns above.
- Opening pass. Is the hook concrete? Does the reader know by the end of page one what the essay is about and why they should keep reading? Cut "how this came to exist" framings from the top; move to appendix.
- Cadence-and-structure pass. The highest-leverage pass. Run it before the surface-level ones below. Read for sentence-length rhythm: if every sentence in a paragraph lands in the same word-count band, break the pattern. Read for paragraph shape: if every paragraph runs the same length, let one go long and one land in a single line. Check paragraph endings: if most close with a summary punchline, cut half of them cold.
- Em dash pass. Search for
—. Cut most. Replace with comma, period, or colon. Keep one or two where emphasis genuinely warrants. A dash-free draft isn't automatically human: GPT-5.1 already suppresses them by default, so absence proves nothing on its own. Treat this as cleanup, not the load-bearing check.
- Vocabulary pass. Search for AI words (
delve, leverage, crucial, etc.). Replace with plainer alternatives.
- Phrase pass. Search for AI tics ("it's worth noting," "at its core," etc.) and reveal-signposting ("here's the thing," "here's the part that..."). Cut the windup; state the point.
- Contrast-and-triad pass. Search for "not X, it's Y" and rule-of-three lists. One of either is fine; repeated across the piece, they're a signature. Cut the repeats.
- Contraction pass. Add contractions where formal writing wouldn't forbid them.
- Cut-for-cream pass. Paul Graham: "Cut as much as possible and serve only the cream." Read each paragraph and ask: does every sentence carry weight? If a sentence only restates the one above it, cut.
- Example density pass. Dan Luu: "Add more examples than you'd naturally tend to." For each abstract claim, check if a concrete example is nearby. If not, add one.
- Read aloud. Clunky phrasing reveals itself when spoken. Fix what sounds wrong.
- Reality check. Would a skeptical reader keep reading past page 2? If not, the opening isn't hooking them.
Exemplars worth studying
Study for voice and structural range, not as templates.
- Dan Luu (danluu.com) — blunt, data-heavy, opinions stated directly. Often starts mid-thought with a concrete example and builds up through accumulated evidence rather than following a fixed arc. Explicit on his blog that copying another writer's style doesn't work.
- Simon Willison (simonwillison.net) — annotated-presentation format for talks, "here's a thing I found and what I made of it" for short posts, pattern-shaped chapters for larger projects. Deliberate choice of form per piece.
- Julia Evans (jvns.ca) — "I struggled with X, here's what I learned" narrative shape. Short. Conversational register. Teaches through a single concrete scenario.
- Paul Graham (paulgraham.com) — essay built around a central surprising claim, with consequences drawn out. "Writing simply keeps you honest." Willing to be brief.
- Matt Levine (Money Stuff) — narrative opening, long paragraphs done well, argumentative work woven into prose rather than sectioned off.
- Bret Victor (worrydream.com) — strong thesis, visual thinking, essay structure chosen to match the argument being made.
- Martin Fowler (martinfowler.com) — named patterns, crisp definitions, concise per-page scope.
What all of them share: structure chosen for the specific piece, not inherited from a template. What none of them do: write every essay to the same skeleton.
Where papers live
Strategic writing (position papers, RFCs, design notes, landscape analyses) typically belongs in a place optimized for reading and sharing — a team wiki, Notion workspace, public blog, or internal documentation portal. Operational references (architecture specs, setup guides, contributing docs, theory-of-operation) typically belong in the code repository next to the artifacts they describe.
The split matters because the audiences differ. Strategic writing is meant to persuade and get reviewed; living next to commits makes it easy for readers to lose the thread. Operational writing is meant to be consulted; living on a separate platform makes it drift from the code.
Cross-reference between the two when appropriate. Don't duplicate. Whichever split your organization uses, name it explicitly so contributors know which kind of writing goes where.
References
Original inventory, plus the 2026-07-24 refresh sources cited in §AI-voice tells to avoid:
