Technical Writing in English Guide: RFC, ADR, Design Doc, and Tech Spec Templates with Practical Expressions

[Document Type Selection Criteria]

1. "I want to gather broad input from the team" --> RFC
   - New technology adoption, process changes, cross-team impacts

2. "I want to record the background and rationale
   of an architecture decision" --> ADR
   - Database selection, framework migration, API design direction

3. "I want to share and get consensus on a detailed
   system design" --> Design Doc
   - New service design, major refactoring, performance optimization

4. "I want to define detailed specs needed
   for implementation" --> Tech Spec
   - API endpoint definitions, data model design, deployment strategy

[RFC Template]

RFC-XXX: Title of the Proposal
Author: Your Name
Status: Draft | In Review | Accepted | Rejected | Superseded
Created: 2026-03-12
Last Updated: 2026-03-12

## Summary
One paragraph summarizing what this RFC proposes and why.

## Motivation
Why is this change needed? What problem does it solve?
Include data, metrics, or user feedback that supports the need.

## Detailed Design
The technical details of the proposal.
- Architecture diagrams
- API changes
- Data model changes
- Migration strategy

## Alternatives Considered
What other approaches were evaluated?
Why were they rejected?

## Risks and Mitigations
What could go wrong? How do we mitigate each risk?

## Success Metrics
How will we measure whether this change was successful?

## Open Questions
What decisions have not yet been made?
What feedback are you specifically looking for?

## References
Links to related documents, prior art, and research.

[Summary Section]

"This RFC proposes migrating our authentication service from a
session-based model to JWT-based authentication."

"The goal of this proposal is to reduce deployment coupling
between the frontend and backend teams."

[Motivation Section]

"Our current system has reached its scalability limits,
with p99 latency exceeding 2 seconds during peak hours."

"Over the past quarter, we have received 15 customer complaints
related to this limitation."

[Alternatives Considered Section]

"We evaluated three alternatives: (1) vertical scaling of the
existing database, (2) introducing a read replica, and
(3) migrating to a distributed database."

"Alternative 1 was rejected because it only delays the problem
by an estimated 6 months without addressing the root cause."

[RFC Status Transition Expressions]

"This RFC is currently in Draft status and open for initial feedback."

"The review period for this RFC closes on March 20, 2026."

"Based on the feedback received, we are updating this RFC
to address the concerns raised about data consistency."

"This RFC has been accepted and will be implemented in Q2 2026."

"This RFC is superseded by RFC-087, which takes a different
approach to solving the same problem."

[ADR Template - Michael Nygard Format]

# ADR-XXX: Title of Decision

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-YYY

## Context
What is the issue that we are seeing that is motivating
this decision or change?

## Decision
What is the change that we are proposing and/or doing?

## Consequences
What becomes easier or more difficult to do because
of this change?

[Extended ADR Example]

# ADR-012: Use PostgreSQL as the Primary Database

## Status
Accepted (2026-03-10)

## Context
Our application currently uses MongoDB for all data storage.
As the product has evolved, we have encountered increasing
challenges with:
- Complex queries requiring multiple aggregation pipelines
- Data consistency issues in transactions spanning
  multiple collections
- Difficulty enforcing referential integrity at the
  database level

The team has spent approximately 20 percent of each sprint
addressing data consistency bugs over the past three months.

## Decision
We will migrate our primary data store from MongoDB to
PostgreSQL for all transactional data. MongoDB will be
retained for the audit log service where its document
model is a natural fit.

## Consequences

### Positive
- ACID transactions will eliminate the consistency bugs
  we have been experiencing
- The team has stronger expertise in relational databases
- Joins will simplify our current multi-query patterns

### Negative
- Migration will require approximately 4 weeks of
  engineering effort
- We will need to maintain two database technologies
  during the transition period
- Some document-oriented patterns will require
  schema redesign

### Risks
- Data migration downtime: mitigated by using a
  dual-write strategy during transition
- Performance regression: mitigated by load testing
  the new schema before cutover

[Context Writing Expressions]

"The current architecture does not support horizontal scaling
beyond 3 nodes without significant operational overhead."

"We need to decide on an approach before the Q3 feature
freeze deadline."

[Decision Writing Expressions]

"We will adopt a strangler fig pattern to incrementally
migrate from the legacy system."

"We will use Protocol Buffers instead of JSON for
inter-service communication."

[Consequences Writing Expressions]

"This decision will increase deployment complexity but
significantly improve runtime performance."

"Teams will need to invest in learning the new technology,
estimated at 2 weeks of ramp-up time per engineer."

[Design Doc Template - Google Style]

Title: [Project Name] Design Document
Author(s): Name (email)
Reviewers: Names
Status: Draft | In Review | Approved
Last Updated: 2026-03-12

## 1. Overview
A brief description of the project, its goals,
and why it matters.

## 2. Background
Relevant context that the reader needs to understand
the rest of the document. Prior art and existing systems.

## 3. Goals and Non-Goals
What this project will and will not accomplish.

## 4. Detailed Design
### 4.1 System Architecture
### 4.2 API Design
### 4.3 Data Model
### 4.4 Algorithms

## 5. Alternatives Considered
Other approaches and why they were rejected.

## 6. Cross-Cutting Concerns
### 6.1 Security
### 6.2 Privacy
### 6.3 Observability

## 7. Migration Strategy
How to get from the current state to the proposed state.

## 8. Open Questions
Unresolved decisions that need input from reviewers.

## 9. Timeline and Milestones
Estimated effort and key milestones.

[Goals and Non-Goals Example]

## Goals
- Reduce API response time for the product search endpoint
  from 800ms (p95) to under 200ms (p95)
- Support real-time indexing of product catalog updates
  with a maximum delay of 30 seconds
- Maintain backward compatibility with existing API clients

## Non-Goals
- This project will NOT address the image search feature
  (tracked separately in Project Atlas)
- Optimizing the recommendation engine is out of scope
  for this design
- We are NOT planning to migrate the entire search
  infrastructure; only the product search endpoint
  is in scope

[Useful Expressions for Non-Goals]

"This is explicitly out of scope for this project."

"While important, this concern will be addressed in
a follow-up project."

"We acknowledge this limitation but consider it acceptable
given the timeline constraints."

[System Architecture Description Expressions]

"The system consists of three main components:
an API gateway, a processing pipeline, and a storage layer."

"Requests flow from the client through the load balancer
to one of N stateless application servers."

"This component is responsible for validating incoming requests
and enriching them with user context before forwarding
to the downstream service."

[API Design Description Expressions]

"The API follows RESTful conventions with the following
endpoints..."

"We chose gRPC over REST for this internal service
because of its lower serialization overhead and
built-in streaming support."

[Tech Spec Template]

Title: [Feature Name] Technical Specification
Author: Name
Approvers: Names
Status: Draft | Approved | Implemented
Sprint/Quarter: Sprint 24 / Q1 2026

## Executive Summary
What are we building and why? (2-3 sentences)

## Technical Requirements
### Functional Requirements
### Non-Functional Requirements
  - Performance targets
  - Availability requirements
  - Security requirements

## System Design
### Architecture Overview
### Component Design
### Data Model / Schema Changes
### API Contracts

## Implementation Plan
### Phase 1: [Description] (Week 1-2)
### Phase 2: [Description] (Week 3-4)

## Testing Strategy
### Unit Tests
### Integration Tests
### Load Tests
### Rollback Plan

## Dependencies
External services, libraries, or teams we depend on.

## Risks and Mitigations
What could go wrong and how we plan to handle it.

## Success Metrics
How we will measure the success of this implementation.

## Appendix
Additional technical details, diagrams, or references.

[Technical Requirements Expressions]

"The system must handle at least 10,000 concurrent connections
with a p99 latency below 100 milliseconds."

"Data at rest must be encrypted using AES-256,
and data in transit must use TLS 1.3."

[Implementation Plan Expressions]

"In Phase 1, we will implement the core data pipeline
and validate it against the existing system using
shadow traffic."

"Phase 2 is gated on the successful completion of
Phase 1 load testing."

[Testing Strategy Expressions]

"We will achieve at least 80 percent code coverage
with unit tests for all new modules."

"The rollback plan involves reverting the feature flag
and restoring the previous database schema via
the automated migration tool."

[Expressions by Feedback Severity]

[Blocker - Must be resolved]
"Blocker: This approach has a potential data loss scenario
that must be addressed before we can approve."

[Major - Significant change needed]
"Major: The proposed caching strategy does not account for
cache invalidation in a multi-region setup."

[Minor - Improvement recommended]
"Minor: Consider adding a sequence diagram to illustrate
the authentication flow."

[Nit - Trivial suggestion]
"Nit: Typo in the API endpoint name on page 3."

[Question - For understanding]
"Question: What happens if the downstream service is
unavailable for more than 5 minutes?"

[Giving Positive Feedback in Reviews]

"This is a well-thought-out design. I especially appreciate
the detailed migration strategy."

"The trade-off analysis in the Alternatives section is
very thorough."

"I like how you have explicitly called out the non-goals.
This helps set clear expectations."

"Strong proposal overall. I have a few minor suggestions below."

[Expressing Constructive Disagreement]

"I have a concern about the proposed approach.
Have we considered the impact on the billing service?"

"I think there might be a simpler approach here.
What if we used an event-driven architecture instead?"

"While I agree with the overall direction, I am not convinced
that the proposed timeline is realistic given our current
team capacity."

"Could you elaborate on how this handles the edge case
where the user session expires mid-transaction?"

[Common Structural Mistakes and Improvements]

[Mistake 1: Jumping to solution without Problem Statement]

Bad:  "We should use Redis for caching."
Good: "Our API response times have increased by 40 percent
      over the past month due to repeated database queries
      for frequently accessed data. We propose implementing
      a Redis caching layer to reduce database load and
      improve response times."

[Mistake 2: Skipping alternatives analysis]

Bad:  "We decided to use Kubernetes."
Good: "We evaluated three container orchestration options:
      Kubernetes, Docker Swarm, and Amazon ECS.
      We selected Kubernetes because..."

[Mistake 3: Lacking quantitative evidence]

Bad:  "The system is slow."
Good: "The system currently has a p95 latency of 1.2 seconds,
      which exceeds our SLA target of 500 milliseconds."

[Mistake 4: Missing Success Metrics]

Bad:  "This change will improve performance."
Good: "Success will be measured by:
      - p95 latency reduction from 1.2s to under 500ms
      - Error rate below 0.1 percent
      - Zero data loss during migration"

[Common English Mistakes in Technical Documents]

[Article (a/the) misuse]
Bad:  "System handles request and sends response."
Good: "The system handles a request and sends a response."

[Tense mixing]
Bad:  "The service received a request and processes it."
Good: "The service receives a request and processes it."
      (Unified present tense for describing system behavior)

[Passive voice overuse]
Bad:  "The data is being processed by the pipeline and
      is then stored by the database."
Good: "The pipeline processes the data and stores it
      in the database."

[Wordy expressions]
Bad:  "In order to achieve the purpose of reducing latency..."
Good: "To reduce latency..."

[Subject omission (Japanese/Korean language habit)]
Bad:  "Should consider using connection pooling."
Good: "We should consider using connection pooling."

[5-Step Technical Document Writing Workflow]

Step 1: Outline First
- Fill in only the section headings from the template
- Write 1-2 sentences of key message for each section
- Get directional feedback from a mentor or tech lead

Step 2: Write the Core Sections
- Complete the Problem Statement / Context first
- Then write the Proposed Solution / Decision
- Finally, write Alternatives and Trade-offs

Step 3: Add Supporting Details
- Add diagrams, tables, and code examples
- Support claims with quantitative data

Step 4: Internal Review
- Get review from 1-2 trusted colleagues first
- Ask them to check if English expressions are natural

Step 5: Publish and Iterate
- Share with the entire team and collect feedback
- Update the status after incorporating feedback

[RFC Checklist]
- [ ] Does the Summary clearly summarize the proposal
      in one paragraph?
- [ ] Does the Motivation include quantitative data
      or specific examples?
- [ ] Have at least 2 Alternatives been evaluated?
- [ ] Are Open Questions specific?
- [ ] Is the review deadline specified?

[ADR Checklist]
- [ ] Does the Context sufficiently explain the
      decision background?
- [ ] Is the Decision clear and unambiguous?
- [ ] Do Consequences include both positive and
      negative impacts?
- [ ] Can a new team member understand it 6 months later?

[Design Doc Checklist]
- [ ] Are Non-Goals explicitly stated?
- [ ] Is an architecture diagram included?
- [ ] Are Security and Privacy considerations addressed?
- [ ] Is the Migration Strategy realistic?

[Tech Spec Checklist]
- [ ] Are non-functional requirements (performance,
      security, availability) quantitative?
- [ ] Does the Implementation Plan have phased milestones?
- [ ] Does the Testing Strategy include a rollback plan?
- [ ] Are all Dependencies listed?

[Transition Expression Collection]

[From background to proposal]
"Given these constraints, we propose..."

"To address this issue, the following approach is recommended."

[Comparing pros and cons]
"On the one hand... On the other hand..."

"While this approach offers simplicity, it comes at the cost
of flexibility."

[Drawing conclusions]
"Taking all factors into consideration, we recommend..."

"Based on the analysis above, the proposed solution
best balances performance and maintainability."

[Limiting scope]
"This document focuses specifically on..."

"The following topics are covered in a separate document."