Technical Writing and Documentation Questions

I treat RFCs for reliability like engineering designs: clear problem, measurable goals, proposed solution with trade-offs, implementation plan, and success criteria.

Structure I follow:

• Title & Summary: one-paragraph overview and impact.
• Motivation & Context: incident data, SLO breaches, pain points.
• Goals & Acceptance Criteria: target SLOs, error budget impact, KPIs.
• Design: architecture diagram, components touched, sequence flow.
• Implementation Plan: milestones, owner per task, rollback plan, testing (canary, chaos tests).
• Operational Runbook & Rollout: alerts, dashboards, playbook steps.
• Risk & Trade-offs: cost, complexity, latency, partial failure modes.
• Timeline & Metrics: checkpoints and how we’ll measure success.
• Open Questions & Alternatives.

Example (succinct): After repeated cache stampedes caused 2% P99 tail latency spikes, I proposed an RFC to add request coalescing + adaptive TTLs. I included incident logs showing correlation with cache misses, acceptance criteria (reduce P99 by 40%, keep cache hit-rate >85%), a phased rollout (internal canary → 10% prod → 100%), automated canary metrics, and a rollback plan. Stakeholders (app teams, product) approved; implementation rolled out in three sprints and met targets; incident frequency dropped 70%.

What I learned about convincing stakeholders:

• Use data and clear success metrics; link reliability work to business impact (error budget, user transactions).
• Address operational burden up-front (who owns alerts, maintenance cost).
• Break big work into small, shippable increments so risk is visible and reversible.
• Solicit early feedback from engineers who’ll operate the system; incorporate their concerns in the runbook.

Tracking implementation:

• Track RFC as a living doc with linked JIRA/issue IDs and a checklist of milestones.
• Add automated dashboards for acceptance criteria; gate rollouts on metrics.
• Hold short weekly syncs during rollout and a blameless post-implementation review that updates the RFC and runbook with learnings.

1. Use plain, consistent language + short sentences.

• Why: Reduces cognitive load for non-native speakers and juniors; makes automated translation more reliable.
• Example: Replace “triage the alarm if CPU throttle occurs” with “When CPU usage > 90% for 5 min, follow the recovery steps below.” Add a glossary for unavoidable terms (e.g., “throttle,” “OOM”).

2. Structure documents for skimmability and role-based use.

• Why: Helps juniors and on-call responders find steps quickly; screen readers and translators work better with consistent headings and lists.
• Example: Runbook layout: Purpose → Pre-req checklist → Step-by-step remediation (numbered) → Verification steps → Rollback → Contacts. Each step begins with the action (verb-first). Provide a TL;DR checklist at top.

3. Add multi-modal aids and accessibility features.

• Why: Supports users with visual/hearing impairments and those who learn better from visuals.
• Example: Include annotated screenshots with alt text, short screencast videos with captions, keyboard-friendly command blocks, and ARIA-compatible HTML for internal docs. Provide a plain-text digest for screen readers and an exported PDF with tagged accessibility.

These practices improve clarity, speed up incident response, and make knowledge accessible to a broader team.