ドキュメントライター

このスキルは、PRD（docs/prd.md）を参照しながらドキュメント執筆を支援します。

前提条件

• プロダクト要求仕様書（PRD）は docs/prd.md に集約されている
• PRD には、プロダクトの概要、機能要件、技術要件、用語定義などが記載されている

執筆ワークフロー

1. コンテキスト確認

ドキュメント作成を開始する前に以下を確認：

1. docs/prd.md を読み込み、プロダクトの全体像を把握する
2. ユーザーに以下を確認：
   • 作成するドキュメントの種類（技術仕様書、ユーザーガイド、API ドキュメントなど）
   • 対象読者（開発者、エンドユーザー、ステークホルダーなど）
   • ドキュメントの目的と期待される成果

2. ドキュメント種類と構成

技術仕様書

# [機能名] 技術仕様書

## 概要
## 背景と目的
## 技術要件
## アーキテクチャ
## API 設計
## データモデル
## セキュリティ考慮事項
## テスト計画
## 制約事項

ユーザーガイド

# [プロダクト名] ユーザーガイド

## はじめに
## クイックスタート
## 基本的な使い方
## 機能詳細
## トラブルシューティング
## FAQ

API ドキュメント

# [API名] API リファレンス

## 概要
## 認証
## エンドポイント一覧
## リクエスト/レスポンス形式
## エラーコード
## 使用例
## レート制限

設計ドキュメント

# [機能名] 設計ドキュメント

## 概要
## 問題定義
## 解決アプローチ
## 設計詳細
## 代替案の検討
## トレードオフ
## 実装計画

3. 執筆プロセス

ステップ 1: PRD との整合性確認

• docs/prd.md から関連するセクションを特定
• PRD に記載された用語定義（Glossary）を参照し、一貫した用語を使用
• PRD の機能要件と技術要件を正確に反映

ステップ 2: アウトライン作成

• ドキュメント種類に応じた構成を提案
• ユーザーと構成を確認・調整
• 各セクションの概要を箇条書きで整理

ステップ 3: セクションごとの執筆

各セクションについて：

1. PRD から関連情報を抽出
2. 対象読者に適した表現で記述
3. 必要に応じて図表やコード例を追加
4. ユーザーからのフィードバックを反映

ステップ 4: レビューと改善

• ドキュメント全体の一貫性を確認
• 用語の統一性をチェック
• 冗長な表現を削除
• リンクや参照の正確性を検証

4. 品質基準

必須要件

• PRD との整合性が取れている
• 対象読者に適した表現を使用している
• 用語が PRD の定義と一致している
• 構造が論理的で読みやすい

推奨事項

• 具体的な例やコードサンプルを含む
• 図表で複雑な概念を視覚化
• 関連ドキュメントへのリンクを記載
• 変更履歴を管理

5. ファイル命名規則

作成するドキュメントは以下の命名規則に従う：

• 技術仕様書: docs/specs/[feature-name]-spec.md
• ユーザーガイド: docs/guides/[topic]-guide.md
• API ドキュメント: docs/api/[api-name]-api.md
• 設計ドキュメント: docs/design/[feature-name]-design.md

執筆時の原則

簡潔さ

• 一文は短く、明確に
• 不要な修飾語を避ける
• 箇条書きを効果的に使用

具体性

• 抽象的な説明よりも具体例を優先
• 数値や具体的な条件を明記
• 曖昧な表現（「など」「〜的な」）を最小限に

一貫性

• PRD で定義された用語を使用
• 文体を統一（です・ます調 or である調）
• フォーマットを統一

読者視点

• 対象読者の前提知識を考慮
• 専門用語には説明を追加
• 読者が求める情報を優先して配置

インタラクティブな執筆

ユーザーとの対話を通じてドキュメントを改善：

1. 明確化の質問: 不明点があれば積極的に質問
2. 段階的な確認: セクションごとにフィードバックを求める
3. 選択肢の提示: 複数のアプローチがある場合は選択肢を提示
4. 改善提案: より良い表現や構成があれば提案

PRD 参照のベストプラクティス

• PRD の「Intro & Goal」セクションから背景情報を取得
• 「What is it?」セクションから機能詳細を参照
• 「Glossary」から正式な用語定義を使用
• 「Tech Notes」から技術的な制約を確認