Turn Saved Research into Finished Output: A Guide for Developers and Engineers Managing

The Question Nobody Can Answer in the Standup

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.

---

The Technical Writer-Manager's Key Output Types

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.

---

The Knowledge-to-Document Workflow

Step 1: Define the document's claim or decision

Before retrieving from the knowledge library, state in one sentence what the document is trying to establish:

• ADR: "We are adopting Kafka over RabbitMQ for our event streaming layer."
• RFC: "We should migrate from REST to GraphQL for our mobile API layer."
• Technical proposal: "We should invest in a dedicated observability platform rather than continuing to use ad-hoc log analysis."
• Runbook: "This document describes how to diagnose and resolve high-latency alerts in the Order Processing service."

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.

Step 2: Retrieve the relevant knowledge

With the claim defined, retrieve from the knowledge library the captures that bear on it:

• For technology selection ADRs: pull the evaluation sub-Collection (all benchmarks, comparisons, documentation pages, and expert perspectives gathered during the evaluation)
• For design documents: pull architecture pattern captures relevant to the design domain
• For runbooks: pull incident captures and post-mortem notes from previous incidents in this area
• For technical proposals: pull the evidence base — performance data, reliability incident captures, tool evaluation results

The retrieval should be structured around the document's argument:

• What evidence supports the chosen approach?
• What evidence documents the alternatives that were considered?
• What evidence establishes the constraints that made the decision non-obvious?

Step 3: Synthesize before writing

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.

Step 4: Write from the synthesis, not from raw captures

The document structure follows from the synthesis. For an ADR:

1. Context: Why is this decision being made now? What problem are we solving?
2. Decision: What have we decided?
3. Alternatives considered: What else was evaluated? (Drawn from evaluation captures)
4. Rationale: Why this approach over the alternatives? (Drawn from synthesis)
5. Consequences: What are the known trade-offs and risks? (Drawn from synthesis + constraints)

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."

---

Producing Specific Document Types

ADRs: the evidence-grounded format

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

## Status
Accepted — 2026-12-01

## Context
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).

## Candidates Evaluated
- Apache Kafka
- RabbitMQ  
- AWS Kinesis

*Full evaluation captures in WebSnips collection: "TE: Event Streaming — Q4 2026"*

## Decision
We will implement Kafka as our event streaming layer.

## Rationale
1. **Throughput:** Kafka sustained 180k msg/sec in our POC benchmark vs. RabbitMQ's 
   65k msg/sec at the same node count. At projected Q3 load, RabbitMQ would require 
   ~3x horizontal scaling.
2. **Operational pattern:** Discord (8k messages/sec → 250k messages/sec over 3 years) 
   and Shopify (product event bus) both document positive Kafka experiences at our 
   projected scale. RabbitMQ is consistently recommended below 30k messages/sec.
3. **Kinesis eliminated:** AWS lock-in risk, shard-level throughput limits 
   (1MB/sec per shard) require complex sharding management at our scale.

## Consequences
**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: 
  1. Checked memory by pod → elevated in 2 of 4 worker pods
  2. Checked queue depth via /metrics/queue-depth → 14,000 jobs queued
  3. Correlated with payment API latency spike in Datadog → confirmed root cause
Resolution: Restarted worker pods to flush queue; payment team had fixed API in parallel

Becomes runbook section:

## Diagnosis
1. Check memory by pod: kubectl top pods -n order-processing
2. If specific workers are elevated: check queue depth at /metrics/queue-depth
3. If queue depth > 5,000: correlate with payment API latency in Datadog 
   (dashboard: [link]) — slow payment API is the most common root cause (4 of 5 incidents)
4. If queue depth normal and all workers elevated: different root cause — see "Memory 
   Leak (Non-Queue)" section

## Resolution (Queue Buildup Path)
1. kubectl rollout restart deployment/order-processing-worker
2. Verify memory stabilizes within 5 minutes
3. Alert #payment-on-call about slow API if confirmed

The runbook is better because it's derived from real patterns ("4 of 5 incidents"), not from hypothetical thinking.

---

Engineering Blog Posts from the Knowledge Library

Why technical content is easy to produce from a knowledge library

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:

1. Identify a capture (or cluster of captures) that contains a specific, non-obvious insight
2. The test: "Would this surprise or help an engineer who hadn't worked through this specific problem?" If yes, it's blog material.
3. Structure the post around the insight:
   • Background: what situation led to discovering this?
   • Discovery: what did we find (the specific insight)?
   • Solution: what did we do about it?
   • Generalization: what does this tell engineers in similar situations?

Examples of knowledge library captures that produce blog posts:

• A specific debugging discovery (race condition in Bull queue that took 3.5 hours to find — what made it hard and how you finally found it)
• A tool evaluation with surprising results (benchmark results that contradicted conventional wisdom)
• An architectural decision with non-obvious trade-offs (why you chose X over Y when most engineering teams choose Y)
• An incident post-mortem pattern (the same category of failure occurred 3 times before you understood the root cause)

---

Worked Example: An RFC Produced From an Evaluation Knowledge Library

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:

• 4 benchmark comparisons from engineering blogs (Apollo blog, Shopify, GitHub, and one independent analysis)
• 7 Stack Overflow and GitHub issue captures about GraphQL operational complexity
• 2 captures from teams that switched back from GraphQL to REST (with reasons)
• 3 captures from teams that successfully adopted GraphQL at mobile scale
• 1 capture: the team's specific API performance data (mobile endpoint response time distribution, showing P99 at 2.3 seconds — the primary motivator)

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:

• Section 1 (Why now): mobile P99 response time data from Datadog, specific endpoints, specific impact on user retention (from product team's analysis)
• Section 2 (GraphQL benefits): 3 specific claims, each with cited source from knowledge library
• Section 3 (Counterarguments): 2 counterarguments addressed honestly with citations from "teams that switched back" captures — and the specific reason those teams failed (schema design, not technology)
• Section 4 (Implementation approach): DataLoader pattern for N+1 problem, Apollo Server caching configuration, proposed migration sequence
• Section 5 (Success criteria): specific P99 mobile response time targets

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."

---

Key Takeaways

1. Define the document's claim first: the claim determines what to retrieve from the knowledge library — everything retrieved should support the claim, document alternatives, or acknowledge constraints.
2. Synthesize before writing: the synthesis note is the intellectual work; the document is the synthesis in presentation format.
3. Cite specific captures: ADRs and RFCs built from cited evidence are more defensible than those that assert conclusions; the knowledge library makes citation effortless.
4. Runbooks produced from real incident patterns are more reliable than theoretical runbooks: the incident captures are the raw material; the diagnosis steps and resolution paths in the runbook should reflect what actually worked across multiple incidents.
5. Engineering blog posts are translations of knowledge library captures: the specific, non-obvious insight is in the library; conversion to blog format is a translation task, not a discovery task.

---

Conclusion

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.

Build your technical knowledge output workflow in WebSnips — use your library of technical captures to write ADRs grounded in evidence, RFCs with cited sources and honest counterarguments, runbooks derived from real incident patterns, and engineering content that shares your team's actual discoveries.