Persona Playbooks
A guide for developers and engineers managing how to turn a saved technical knowledge library into finished output — write better ADRs, RFCs, technical
A new hire on the platform team asks a simple question in her second week: why does the event pipeline run on Kafka instead of RabbitMQ? Three people give three different partial answers, none of them cite anything, and by the end of the conversation nobody is quite sure the reasoning still holds. The decision was right. It just was never written down anywhere a new engineer could find it.
This happens constantly in engineering organizations, and it isn't really a knowledge problem — the senior engineers who made the call still remember most of it. It's a documentation problem: the evidence that justified the call (the benchmarks, the incident history, the vendor comparisons) sat in someone's browser tabs and Slack history instead of an ADR, an RFC, or a runbook that survives past the people who remember the discussion.
For developers and engineers with any technical leadership responsibility, producing ADRs, RFCs, design docs, runbooks, and post-mortems from that scattered research is part of the job description, whether or not it's in the job title. Doing it well means retrieving the specific captures that back a specific claim and turning them into a document someone else can act on without re-litigating the whole investigation.
This guide covers the workflow for doing that reliably — from a technical knowledge library to the documents that make institutional memory actually survive employee turnover.
Engineers and tech leads produce seven types of documents that draw heavily from their technical knowledge base:
1. Architecture Decision Records (ADRs): Formally documented records of significant architectural decisions — what was decided, what alternatives were considered, and why the chosen approach was selected. ADRs are the institutional memory of technical choices.
2. Request for Comments (RFCs): Proposals for significant technical changes or system designs, circulated for team review before implementation. RFCs require evidence-grounded arguments for the proposed approach and honest assessment of alternatives.
3. Technical design documents: Pre-implementation design for specific features or systems, documenting the design decisions, interfaces, data models, and implementation approach. These require drawing on patterns, precedents, and tool knowledge.
4. On-call runbooks: Step-by-step procedures for responding to specific incidents or alert conditions. Good runbooks are derived from post-mortem learning and patterns documented during past incidents.
5. Technical proposals: Arguments for specific technology choices, process changes, or investment decisions directed at engineering leadership or management. These require synthesizing evidence from evaluations, benchmarks, and team experience.
6. Post-mortem documents: Analyses of incidents that capture root cause, timeline, contributing factors, and corrective actions. Post-mortem quality depends on the accuracy and completeness of the knowledge base entries created during and immediately after the incident.
7. Engineering blog posts: External or internal technical content sharing what the team has learned. Blog posts require a clear insight supported by specific technical evidence.
Before retrieving from the knowledge library, state in one sentence what the document is trying to establish:
The claim or decision is the document's spine. Everything retrieved from the knowledge library should either support the claim, document the alternatives considered, or explain the constraints that shaped the decision.
With the claim defined, retrieve from the knowledge library the captures that bear on it:
The retrieval should be structured around the document's argument:
Before writing the document, write a synthesis note that answers: "Given all this evidence, what does it show?"
For a Kafka vs. RabbitMQ ADR:
SYNTHESIS: Kafka vs. RabbitMQ evaluation for event streaming
WHAT THE EVIDENCE SHOWS:
1. Kafka's throughput advantage (2-3x in our benchmark at 50k messages/sec) is significant
for our expected load (projected 80k msg/sec by Q3 2027)
2. RabbitMQ's operational simplicity is real — team familiarity is higher,
initial setup was 40% faster in POC
3. The primary operational risk for Kafka is partition management complexity —
documented in 3 of the 4 "Kafka pitfalls" blog posts we captured
4. Two teams at comparable scale (Discord, Confluent blog) report that Kafka's
operational complexity pays off above 30k messages/sec
THE DECISION:
Adopt Kafka. The throughput ceiling with RabbitMQ would require horizontal scaling
at projected Q3 loads; Kafka handles this natively. Operational complexity is real
but manageable with a dedicated broker team member and the existing runbook library.
WHAT'S STILL UNCERTAIN:
- Long-term operational burden on the team (no production evidence, only blog posts)
- Whether the specific partitioning strategy (by customer_id) will hold at scale
The synthesis is the intellectual work. The ADR is the synthesis formatted for the team's documentation system.
The document structure follows from the synthesis. For an ADR:
Each section draws from specific captures in the knowledge library, not from memory. The ADR that cites "benchmark results from our November 2026 POC" and "Discord Engineering's post on Kafka partition management" is more defensible than one that asserts "Kafka is better for high throughput."
ADRs should be the team's most retrievable technical documents. The knowledge library is the evidence base; the ADR is the synthesis.
Standard ADR format with knowledge library integration:
# ADR-042: Event Streaming Layer Selection
Accepted — 2026-12-01
Our current synchronous API-to-API communication between Order Processing and Inventory produces inconsistent behavior under high load (documented in incidents INC-2026-0847 and INC-2026-1103). We need an event streaming layer to decouple these services.
Load projections: 50k messages/sec current peak; 80k messages/sec by Q3 2027 (from capacity planning document, Nov 2026).
Full evaluation captures in WebSnips collection: "TE: Event Streaming — Q4 2026"
We will implement Kafka as our event streaming layer.
Positive: Decoupled services enable independent scaling; message persistence enables replay for debugging and late consumers.
Negative: Operational complexity (partition management, consumer group management) requires team investment. Assigned: [Name] to own Kafka operations for Q1 2027.
Risks: Partitioning by customer_id may produce hot partitions for high-volume customers — needs monitoring in first 60 days post-deployment.
The key difference between this ADR and a weak one: every claim cites specific evidence or a specific source. "We will implement Kafka because it's industry standard" is not citable evidence. "Kafka sustained 180k msg/sec in our November 2026 POC benchmark" is.
### RFCs: argument from evidence
RFCs propose significant changes and require team review before implementation. The most effective RFCs are argued, not asserted — they present evidence, acknowledge counterarguments, and make a case rather than announcing a decision.
**The RFC-from-knowledge-library workflow:**
1. Identify the captures that support the proposal
2. Identify the captures that represent the strongest counterarguments
3. Synthesize what the evidence shows — including the uncomfortable evidence
4. Write the RFC with the strongest counterarguments addressed honestly
An RFC that honestly addresses "the main argument against this is X, and our response is Y" is more persuasive than one that ignores X. The knowledge library makes this possible because it contains the counterargument captures alongside the supporting captures — provided you captured honestly during the research phase.
### On-call runbooks from incident captures
Runbooks should be produced from accumulated incident knowledge, not from hypothetical thinking about what might go wrong.
**The runbook production workflow:**
1. Pull all incident captures related to the service/alert from the knowledge library
2. Identify the pattern across incidents: what conditions trigger the alert? What diagnosis steps have worked? What resolution paths have been effective?
3. Write the runbook from the patterns, not from theory
A runbook derived from 8 real incidents is more reliable than one derived from theoretical failure modes. The knowledge library, when it contains detailed incident captures with diagnosis and resolution steps, is the raw material for high-quality runbooks.
**From incident capture to runbook section:**
Incident capture:
Incident: INC-2026-1103 — Order processing memory spike Root cause: Slow payment API responses causing queue buildup (jobs not completing in time, new jobs queuing faster than old ones completing) Diagnosis path:
Becomes runbook section:
The runbook is better because it's derived from real patterns ("4 of 5 incidents"), not from hypothetical thinking.
---
An engineering blog post requires one thing above all else: a specific, credible technical insight. Generic blog posts ("how we think about reliability") are forgettable. Specific blog posts ("how we discovered Kafka hot partitions were silently dropping 0.3% of our order events, and what we did about it") are memorable and useful.
The knowledge library contains the specific technical insights — they're in the incident captures, the debugging sessions, the tool evaluation summaries, the architecture decisions. Converting them to blog posts is a translation task, not a discovery task.
The blog post conversion workflow:
Examples of knowledge library captures that produce blog posts:
The scenario: An engineering team is evaluating whether to migrate from REST to GraphQL for their mobile API. The senior engineer wants to produce a compelling RFC that the team will take seriously.
Knowledge library available:
"TE: GraphQL vs REST — Mobile API Q4 2026" Collection contains:
Synthesis note: "GraphQL's main benefit for mobile is query flexibility (clients request exactly what they need) which reduces over-fetching. Our P99 mobile response time of 2.3 sec is largely driven by over-fetching on 3 endpoints (confirmed from Datadog). GraphQL would address this directly. The operational complexity objection is real but concentrated in N+1 query problems and caching complexity — both have established solutions (DataLoader, Apollo Server's caching layer). The 2 'we switched back' cases both cite poor initial schema design as the actual failure, not GraphQL itself. Net: migration is warranted; the risk is in implementation quality, not the technology."
RFC produced:
3,000-word RFC document built directly from the synthesis:
Team review outcome: RFC approved after one round of review. Engineering manager's comment: "Best RFC I've reviewed this year — every claim has a source and you addressed the counterarguments I expected to bring up."
The gap between accumulated technical knowledge and documented organizational knowledge is where institutional memory is lost. The ADR that's never written because "everyone knows why we made that decision" becomes the decision no one can explain 18 months later. The runbook that was never produced from the post-mortem becomes the same incident recurring with the same 12-minute escalation delay. The engineering blog post that was never extracted from the debugging discovery becomes knowledge that leaves with the engineer. The knowledge library converts the accumulation of technical knowledge into the raw material for the documents that preserve it. The workflow — claim, retrieve, synthesize, write — is the discipline that converts the library into organizational output, making individual technical knowledge into team capability.
For more on this, see Clip Articles for Later Reading.
More WebSnips articles that pair well with this topic.
A guide for educators and course creators on how to turn saved research into finished output — build better lesson plans, course modules, assessments, and
A guide for lawyers on how to turn saved research into finished output — write better client memos, regulatory analyses, briefs, due diligence summaries
A guide for remote team leads on how to turn saved research into finished output — write better team protocols, onboarding documents, async communication
A guide for PKM and tools enthusiasts on how to turn a saved research library into finished output — overcome the perpetual preparation trap, write from
A guide for marketers on how to turn a saved marketing intelligence library into finished output — write better campaign briefs, creative strategy
A guide for knowledge workers and consultants on how to turn a saved intelligence library into finished deliverables — produce better strategy memos