technical-analytical-writing

Technical Analytical Writing

Communicate complex technical ideas clearly through structured analysis and evidence-based reasoning.

Document Types

Architecture Decision Record (ADR)

# ADR-{NNN}: {Decision Title}

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-{NNN}
**Date:** YYYY-MM-DD
**Deciders:** {names/roles}

## Context

What is the issue that motivates this decision? What forces are at play?

## Decision

What is the change being proposed or decided?

## Consequences

### Positive
- {benefit}

### Negative
- {tradeoff}

### Neutral
- {observation}

## Alternatives Considered

### {Alternative A}
- Pros: {list}
- Cons: {list}
- Why rejected: {reason}

System Analysis Document

# {System/Component} Analysis

## Executive Summary
{2-3 sentences: what, why, recommendation}

## Current State
{What exists today, with evidence}

## Problem Statement
{Specific, measurable issue being addressed}

## Analysis
{Evidence-based investigation}

## Recommendations
{Ordered by priority, with effort estimates}

## Appendix
{Raw data, detailed metrics, supplementary evidence}

Technical RFC

# RFC: {Title}

**Author:** {name}
**Status:** Draft | Review | Accepted | Rejected
**Created:** YYYY-MM-DD
**Review deadline:** YYYY-MM-DD

## Summary
{One paragraph: what this proposes}

## Motivation
{Why this is needed, with concrete examples}

## Detailed Design
{How it works, with diagrams and code examples}

## Drawbacks
{Honest assessment of downsides}

## Alternatives
{What else was considered and why this approach wins}

## Unresolved Questions
{Open items for discussion}

Writing Principles

Argument Structure

Every analytical section follows:

1. Claim — What you're asserting
2. Evidence — Data, metrics, code examples supporting the claim
3. Reasoning — Why the evidence supports the claim
4. Implication — What follows from this being true

Evidence Hierarchy

Strength	Evidence Type	Example
Strongest	Production metrics	"P99 latency increased 3x after migration"
Strong	Reproducible test	"Benchmark shows 40ms vs 120ms"
Moderate	Code analysis	"This pattern creates N+1 queries"
Weak	Expert opinion	"The team believes this will scale"
Weakest	Analogy	"Netflix does it this way"

The Pyramid Principle

Lead with the conclusion, then support:

Bad:

We analyzed the database, then the cache layer, then the API, and found that response times are slow because the cache hit rate is only 23%.

Good:

Cache hit rate is 23%, causing slow response times. The database query layer generates cache keys inconsistently, leading to unnecessary misses. Standardizing key generation would bring hit rate to ~85%.

Structural Patterns

Problem-Solution-Evidence

## {Problem Name}

**Problem:** {specific, measurable issue}

**Solution:** {proposed change}

**Evidence:** {why this solution addresses the problem}

**Effort:** {T-shirt size + key dependencies}

Compare-Contrast Table

| Criterion | Option A | Option B | Option C |
|-----------|----------|----------|----------|
| Performance | ★★★ | ★★ | ★★★ |
| Complexity | Low | Medium | High |
| Team familiarity | High | Low | Medium |
| Maintenance cost | Low | High | Medium |
| **Recommendation** | **✓** | | |

Risk Matrix

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| API rate limiting | High | Medium | Client-side rate limiter + cache |
| Data migration failure | Low | Critical | Rollback plan + dry-run first |
| Team bandwidth | Medium | High | Phased rollout |

Style Guidelines

Clarity

• Active voice: "The scheduler triggers the job" not "The job is triggered by the scheduler"
• Concrete nouns: "The API returns a 429 status" not "There are issues with the API"
• Specific numbers: "P99 latency is 230ms" not "Latency is high"

Conciseness

• Lead with the point, not the preamble
• One idea per paragraph
• Cut "In order to" → "To"
• Cut "It is important to note that" → (just state it)
• Cut "As mentioned previously" → (don't mention it)

Technical Accuracy

• Verify all metrics and measurements
• Include measurement methodology
• Distinguish between observations and interpretations
• Cite sources for external claims
• Date all data ("as of March 2026")

Diagrams

When to Use Diagrams

Situation	Diagram Type
System components	Architecture diagram (boxes + arrows)
Process flow	Flowchart or sequence diagram
Data relationships	ER diagram
Timeline	Gantt or timeline
Hierarchy	Tree diagram
Comparison	Table (not a diagram)

Mermaid for Inline Diagrams

```mermaid
graph LR
    A[Client] --> B[API Gateway]
    B --> C[Auth Service]
    B --> D[Skills Service]
    D --> E[(Database)]
```

Review Checklist

• Executive summary is self-contained (reader gets the point without reading further)
• Every claim has supporting evidence
• Alternatives are fairly presented (not strawmen)
• Risks and tradeoffs acknowledged honestly
• Audience-appropriate level of detail
• Diagrams have legends and labels
• All acronyms defined on first use
• Stranger test: a new team member can follow the argument

Anti-Patterns

• Burying the lead — Put conclusions first, evidence after
• Appeal to authority — "Google does it" is not an argument; explain why it works
• False precision — "This will improve performance by 47.3%" without measurement methodology
• Missing alternatives — Always compare at least 2-3 options
• Scope creep — Stay focused on the stated question; flag tangents for separate docs
• No expiration date — All analysis should include "valid as of" and conditions for revisiting