Dog Writing — Technical Writing Patterns

When to Activate

• Writing a PRD (Product Requirements Document)
• Documenting an architectural decision (ADR)
• Creating a feature tech spec
• Writing a PR description
• Formatting a commit message
• Writing a code review comment

PRD Template

# [Feature Name] — PRD

## Problem Statement
[What is broken or missing? 2-3 sentences max.]

## Hypothesis
If [we do X], then [Y outcome] because [Z reason].

## Success Metrics
- Primary metric: [measurable with baseline — e.g. "response time < 200ms p99"]
- Secondary metric: [optional]

## User Story
As a [user/system], I want [capability], so that [measurable benefit].

## Scope

### In Scope
- [specific item 1]
- [specific item 2]

### Out of Scope
- [item 1] — reason: [explicit rationale]
- [item 2] — reason: [explicit rationale]

## Design
[Wireframe, sequence diagram, or step-by-step flow description]

## Technical Approach
[Technical summary — 1 paragraph. Mention: stack, pattern, main dependencies]

## Risks
| Risk | Probability | Impact | Mitigation |
|---|---|---|---|
| [risk 1] | High/Medium/Low | High/Medium/Low | [action] |

## Open Questions
- [ ] [question that must be answered before implementing]

## Implementation Phases
1. **[Phase 1]** — [description] — status: pending
2. **[Phase 2]** — [description] — status: pending

ADR Template

# ADR-[NNN]: [Descriptive Decision Title]

## Status
[proposed | accepted | deprecated | superseded by ADR-XXX]

## Context
[Current situation. What made this decision necessary. Forces at play.
Be specific: "we have 50K req/min at p99 of 800ms, we need < 200ms"]

## Decision
[The decision made. Active, direct voice.
E.g.: "We will use Redis for session cache with a 1-hour TTL."]

## Consequences

### Positive
- [concrete benefit 1]
- [concrete benefit 2]

### Negative / Trade-offs
- [cost or limitation 1]
- [cost or limitation 2]

### Alternatives Considered
- **[Option A]**: [brief description] — rejected because [specific reason]
- **[Option B]**: [brief description] — rejected because [specific reason]

## Date
[YYYY-MM-DD]

PR Description Template

## What

[One line: "Add X to Y" or "Fix Z in W"]

## Why

Closes #[issue-number] — [one line explaining the problem being solved]

## How

- [key technical decision 1 — e.g.: "Uses strategy pattern to avoid a growing switch"]
- [key technical decision 2 — e.g.: "In-memory cache with 5min TTL to reduce queries"]
- [non-obvious decision 3 — e.g.: "No DB transaction here because X"]

## Testing

- [ ] Unit tests: [what was covered]
- [ ] Manually tested on: [browser/env/specific case]
- [ ] Edge cases: [list the non-obvious ones]

## Notes for the Reviewer

[Context that makes review easier. Decisions that may look odd but are intentional.]

Commit Message Format

Follow Conventional Commits:

<type>(<scope>): <imperative description, no trailing period>

[optional body — explains WHAT and WHY, not how]

[optional footer — Closes #123, BREAKING CHANGE: desc]

Types: feat | fix | refactor | test | docs | chore | perf | ci | build

Examples:

feat(auth): add OAuth2 Google login

Implements Google OAuth2 using Passport.js strategy.
Stores minimal profile (id, email, name) after successful auth.

Closes #42

fix(api): prevent null pointer on empty ticket list

The /tickets endpoint crashed when HaloPSA returned an empty array.
Added early return guard before mapping.

perf(scraper): reduce page load time by 40% blocking media assets

Blocks images, fonts, and tracking scripts via context.route().
Tested on 200-page crawl: 45s → 27s.

Technical Writing Principles

1. Specific > vague: "Redis cache with 5min TTL" > "Add cache"
2. Justify decisions: "We chose X because Y" — always include the why
3. Explicit out-of-scope: list what will NOT be done and why
4. Measurable criteria: "< 200ms p99" > "fast response"
5. Active voice: "The system validates X" > "X is validated by the system"
6. No redundancy: every word must add value — cut what does not