技術文書英語ライティングガイド: RFC·ADR·Design Doc·Tech Specテンプレートと実践表現

[文書タイプ選択基準]

1. "チームの意見を広く求めたい" --> RFC
   - 新技術導入、プロセス変更、クロスチーム影響が大きい変更

2. "アーキテクチャ決定の背景と根拠を残したい" --> ADR
   - データベース選択、フレームワーク移行、API設計方針

3. "システム設計を詳細に共有し合意を得たい" --> Design Doc
   - 新サービス設計、大規模リファクタリング、性能最適化プロジェクト

4. "実装に必要な詳細仕様を定義したい" --> Tech Spec
   - APIエンドポイント定義、データモデル設計、デプロイ戦略

[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 セクション]

"This RFC proposes migrating our authentication service from a
session-based model to JWT-based authentication."
(このRFCは認証サービスをセッションベースモデルから
JWT認証への移行を提案します。)

"The goal of this proposal is to reduce deployment coupling
between the frontend and backend teams."
(この提案の目標はフロントエンドとバックエンドチーム間の
デプロイ結合度を削減することです。)

[Motivation セクション]

"Our current system has reached its scalability limits,
with p99 latency exceeding 2 seconds during peak hours."
(現在のシステムはスケーラビリティの限界に達しており、
ピーク時にp99レイテンシが2秒を超えています。)

"Over the past quarter, we have received 15 customer complaints
related to this limitation."
(過去四半期で、この制限に関連する15件の顧客クレームを受けました。)

[Alternatives Considered セクション]

"We evaluated three alternatives: (1) vertical scaling of the
existing database, (2) introducing a read replica, and
(3) migrating to a distributed database."
(3つの代替案を評価しました：（1）既存データベースの垂直スケーリング、
（2）リードレプリカの導入、（3）分散データベースへの移行。)

"Alternative 1 was rejected because it only delays the problem
by an estimated 6 months without addressing the root cause."
(代替案1は根本原因を解決せず問題を約6ヶ月先送りするだけなので
却下されました。)

[RFCステータス遷移表現]

"This RFC is currently in Draft status and open for initial feedback."
(このRFCは現在ドラフト状態で、初期フィードバックを受け付けています。)

"The review period for this RFC closes on March 20, 2026."
(このRFCのレビュー期間は2026年3月20日に終了します。)

"Based on the feedback received, we are updating this RFC
to address the concerns raised about data consistency."
(受け取ったフィードバックに基づき、データ整合性について
提起された懸念に対応するためこのRFCを更新しています。)

"This RFC has been accepted and will be implemented in Q2 2026."
(このRFCは承認され、2026年第2四半期に実装される予定です。)

"This RFC is superseded by RFC-087, which takes a different
approach to solving the same problem."
(このRFCは同じ問題を異なるアプローチで解決する
RFC-087に置き換えられました。)

[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 記述表現]

"The current architecture does not support horizontal scaling
beyond 3 nodes without significant operational overhead."
(現在のアーキテクチャは大幅な運用オーバーヘッドなしには
3ノード以上の水平スケーリングをサポートしません。)

"We need to decide on an approach before the Q3 feature
freeze deadline."
(Q3機能フリーズ期限前にアプローチを決定する必要があります。)

[Decision 記述表現]

"We will adopt a strangler fig pattern to incrementally
migrate from the legacy system."
(レガシーシステムから段階的に移行するために
strangler figパターンを採用します。)

"We will use Protocol Buffers instead of JSON for
inter-service communication."
(サービス間通信にJSONの代わりにProtocol Buffersを使用します。)

[Consequences 記述表現]

"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."
(チームは新技術の学習に投資する必要があり、
エンジニア1人あたり約2週間の立ち上げ時間が見込まれます。)

[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 記述例]

## 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

[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."
(この制限を認識していますが、スケジュールの制約を考慮すると
許容可能と判断します。)

[システムアーキテクチャ説明表現]

"The system consists of three main components:
an API gateway, a processing pipeline, and a storage layer."
(システムは3つの主要コンポーネントで構成されています：
APIゲートウェイ、処理パイプライン、ストレージレイヤー。)

"Requests flow from the client through the load balancer
to one of N stateless application servers."
(リクエストはクライアントからロードバランサーを通じて
N個のステートレスアプリケーションサーバーの1つに流れます。)

"This component is responsible for validating incoming requests
and enriching them with user context before forwarding
to the downstream service."
(このコンポーネントは受信リクエストを検証し、ダウンストリーム
サービスに転送する前にユーザーコンテキストを付加する役割を持ちます。)

[API設計説明表現]

"The API follows RESTful conventions with the following
endpoints..."
(APIはRESTfulな規則に従い、以下のエンドポイントを含みます...)

"We chose gRPC over REST for this internal service
because of its lower serialization overhead and
built-in streaming support."
(この内部サービスにRESTではなくgRPCを選択した理由は、
シリアライゼーションオーバーヘッドが低く、ストリーミング
サポートが内蔵されているためです。)

[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 表現]

"The system must handle at least 10,000 concurrent connections
with a p99 latency below 100 milliseconds."
(システムはp99レイテンシ100ミリ秒未満で
最低10,000の同時接続を処理できなければなりません。)

"Data at rest must be encrypted using AES-256,
and data in transit must use TLS 1.3."
(保存データはAES-256で暗号化し、
転送中データはTLS 1.3を使用しなければなりません。)

[Implementation Plan 表現]

"In Phase 1, we will implement the core data pipeline
and validate it against the existing system using
shadow traffic."
(フェーズ1では、コアデータパイプラインを実装し、
シャドウトラフィックを使用して既存システムと比較検証します。)

"Phase 2 is gated on the successful completion of
Phase 1 load testing."
(フェーズ2はフェーズ1の負荷テストの成功完了を前提とします。)

[Testing Strategy 表現]

"We will achieve at least 80 percent code coverage
with unit tests for all new modules."
(すべての新モジュールに対してユニットテストで
最低80パーセントのコードカバレッジを達成します。)

"The rollback plan involves reverting the feature flag
and restoring the previous database schema via
the automated migration tool."
(ロールバック計画はフィーチャーフラグを戻し、
自動移行ツールを通じて以前のデータベーススキーマを
復元することです。)

[重要度別フィードバック表現]

[Blocker - 必ず解決すべき]
"Blocker: This approach has a potential data loss scenario
that must be addressed before we can approve."
(ブロッカー：このアプローチには潜在的なデータ損失シナリオがあり、
承認前に必ず対処が必要です。)

[Major - 重要な変更が必要]
"Major: The proposed caching strategy does not account for
cache invalidation in a multi-region setup."
(メジャー：提案されたキャッシュ戦略はマルチリージョン構成での
キャッシュ無効化を考慮していません。)

[Minor - 改善推奨]
"Minor: Consider adding a sequence diagram to illustrate
the authentication flow."
(マイナー：認証フローを説明するシーケンスダイアグラムの
追加を検討してください。)

[Nit - 些細な提案]
"Nit: Typo in the API endpoint name on page 3."
(Nit：3ページ目のAPIエンドポイント名にタイポがあります。)

[Question - 理解のための質問]
"Question: What happens if the downstream service is
unavailable for more than 5 minutes?"
(質問：ダウンストリームサービスが5分以上利用不可の場合
どうなりますか？)

[レビューでポジティブフィードバックを与える]

"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."
(Non-Goalsを明示的に記述している点が良いです。
これが明確な期待値の設定に役立っています。)

"Strong proposal overall. I have a few minor suggestions below."
(全体的に強力な提案です。以下にいくつかの軽微な提案があります。)

[建設的に反対意見を述べる]

"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?"
(ユーザーセッションがトランザクション中に期限切れになる
エッジケースをどのように処理するか詳しく説明していただけますか？)

[よくある構造的ミスと改善]

[ミス1: 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."

[ミス2: 代替案分析の省略]

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

[ミス3: 定量的根拠の欠如]

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

[ミス4: 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"

[技術文書でよくある英語の間違い]

[冠詞 (a/the) の誤用]
Bad:  "System handles request and sends response."
Good: "The system handles a request and sends a response."

[時制の混用]
Bad:  "The service received a request and processes it."
Good: "The service receives a request and processes it."
      (システム動作の説明時は現在形で統一)

[受動態の濫用]
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."

[冗長な表現]
Bad:  "In order to achieve the purpose of reducing latency..."
Good: "To reduce latency..."

[主語省略 (日本語/韓国語の習慣)]
Bad:  "Should consider using connection pooling."
Good: "We should consider using connection pooling."

[技術文書作成5ステップワークフロー]

Step 1: Outline First（概要を先に）
- テンプレートのセクション見出しだけをまず埋める
- 各セクションに1-2文のキーメッセージを書く
- この段階でメンターやテックリードに方向性を確認する

Step 2: Write the Core Sections（核心セクション作成）
- Problem Statement / Contextを先に完成させる
- 次にProposed Solution / Decisionを作成する
- 最後にAlternativesとTrade-offsを作成する

Step 3: Add Supporting Details（裏付け資料の追加）
- ダイアグラム、テーブル、コード例を追加する
- 定量的データで主張を裏付ける

Step 4: Internal Review（内部レビュー）
- 信頼できる同僚1-2名にまずレビューを依頼する
- 英語表現が自然かどうか確認を依頼する

Step 5: Publish and Iterate（公開と反復）
- チーム全体に共有しフィードバックを収集する
- フィードバック反映後にステータスを更新する

[RFC チェックリスト]
- [ ] Summaryが1段落で提案を明確に要約しているか？
- [ ] Motivationに定量的データや具体的事例があるか？
- [ ] 最低2つ以上のAlternativesを検討したか？
- [ ] Open Questionsが具体的か？
- [ ] レビュー期限が明示されているか？

[ADR チェックリスト]
- [ ] Contextが意思決定の背景を十分に説明しているか？
- [ ] Decisionが明確で曖昧さがないか？
- [ ] Consequencesにポジティブ/ネガティブ両方の影響があるか？
- [ ] 6ヶ月後の新しいチームメンバーが読んでも理解できるか？

[Design Doc チェックリスト]
- [ ] Non-Goalsが明示されているか？
- [ ] アーキテクチャダイアグラムが含まれているか？
- [ ] SecurityとPrivacyの考慮事項があるか？
- [ ] Migration Strategyが現実的か？

[Tech Spec チェックリスト]
- [ ] 非機能要件（性能、セキュリティ、可用性）が定量的か？
- [ ] Implementation Planにフェーズ別マイルストーンがあるか？
- [ ] Testing Strategyにロールバック計画が含まれているか？
- [ ] すべてのDependenciesがリストアップされているか？

[遷移表現集]

[背景説明から提案へ]
"Given these constraints, we propose..."
(これらの制約を考慮して、我々は提案します...)

"To address this issue, the following approach is recommended."
(この問題に対処するため、以下のアプローチを推奨します。)

[長所と短所の比較]
"On the one hand... On the other hand..."
(一方では... もう一方では...)

"While this approach offers simplicity, it comes at the cost
of flexibility."
(このアプローチは単純さを提供しますが、柔軟性の犠牲が伴います。)

[結論の導出]
"Taking all factors into consideration, we recommend..."
(すべての要素を考慮して、我々は推奨します...)

"Based on the analysis above, the proposed solution
best balances performance and maintainability."
(上記の分析に基づき、提案されたソリューションが
パフォーマンスと保守性を最もよくバランスさせます。)

[スコープの制限]
"This document focuses specifically on..."
(この文書は具体的に以下に焦点を当てています...)

"The following topics are covered in a separate document."
(以下のトピックは別の文書で扱います。)