technical-writing

テクニカルライティング

明確な構成、適切な詳細度、ユーザーを重視した内容で、プロフェッショナルな技術ドキュメントを作成します。

ワークフロー

1. ドキュメントの種類を特定する

必要なドキュメントの種類を判断します。

• API ドキュメント - REST、GraphQL、ウェブフック、認証
• ユーザーガイド - 機能、使い方、トラブルシューティング
• チュートリアル - 実践的な例を用いた学習向けコンテンツ
• アーキテクチャドキュメント - システム設計、技術的な決定事項
• README ファイル - プロジェクトの概要、クイックスタート
• リリースノート - 変更点、移行、互換性を損なう変更
• 技術仕様書 - 要件、制約

詳細なテンプレートとパターンについては、 documentation-types-and-workflows.md を読み込みます。

2. コンテキストを収集する

執筆前に重要な情報を収集します。

• 読者 - 開発者、エンドユーザー、マネージャー、管理者
• 技術的な深さ - 初級、中級、上級
• 範囲 - ドキュメント化するコードベース／API／システム
• 標準 - スタイルガイドや組織の要件
• 関連ドキュメント - 参照または統合する既存のドキュメント

3. コンテンツを構成する

明確に整理するための原則を適用します。

• 概要や導入から始める
• 説明的な見出し階層を使う（H1 → H2 → H3）
• 3つを超えるセクションがあるドキュメントには目次を含める
• 関連情報を論理的にまとめる
• 概念の説明の直後に例を配置する
• 複雑なワークフローには図やビジュアルを追加する

4. 明確な内容を書く

基本的な執筆原則に従います。

• 能動態 - 「API は値を返します」。「応答が返されます」ではありません
• 具体性 - 「応答時間は 200ms 未満」。「高速な応答」ではありません
• 略語の定義 - 初出時に「API（Application Programming Interface）」と記載する
• 用語の一貫性 - ドキュメント全体で同じ用語を使う
• 命令形の指示 - 「コマンドを実行します」。「実行してください」ではありません
• 例を示す - すべての概念にコードや出力例を用意する

包括的なスタイルガイドについては、 writing-guidelines.md を読み込みます。

5. コード例を追加する

コード例の要件：

• コードブロックで言語を指定する：python、javascript
• 完全で実行可能な例を示す（断片ではなく）
• 入力と出力の組み合わせを含める
• 複雑なロジックには説明コメントを追加する
• 公開前にすべてのコードをテストする

6. レビューして検証する

品質保証チェックリスト：

• ✓ 技術的な正確さを確認する
• ✓ すべてのコード例をテストする
• ✓ 明確さと完全性を確認する
• ✓ 用語の一貫性を確保する
• ✓ すべてのリンクと参照を検証する

ドキュメントのテンプレート

README ファイル

プロジェクトドキュメントに必要な要素：

# Project Name
Brief description of what the project does

## Features
- Key feature 1
- Key feature 2
- Key feature 3

## Installation
[step-by-step installation commands]

## Quick Start
[minimal working example]

## Configuration
[environment variables or config options]

## License
[license type]

リリースノート

バージョンリリースの構成：

# Version X.X.X - YYYY-MM-DD

## Summary
[High-level overview of this release]

## New Features
- Feature description (#issue-number)
- Feature description (#issue-number)

## Bug Fixes
- Fix description (#issue-number)
- Fix description (#issue-number)

## Breaking Changes
⚠️ **Change that breaks compatibility**
Migration guide: [step-by-step migration instructions]

## Deprecations
- Deprecated feature (will be removed in vX.X)

品質基準

公開前のドキュメント品質チェックリスト：

• 正確さ - 技術的な詳細がすべて正しい
• 完全性 - 必要なトピックをすべて網羅している
• 明確さ - 対象読者が内容を理解できる
• 例 - 動作するコードを含め、テストしている
• 構成 - 論理的に整理され、見出しが明確である
• 一貫性 - 用語と書式に一貫性がある
• リンク - すべてのハイパーリンクが有効である
• 文法 - スペルや文法に誤りがない
• 最新性 - バージョン番号と日付が最新である

避けるべきよくある落とし穴

1. 知識があると決めつける - すべての略語と技術用語を定義する
2. 曖昧な指示 - 具体例を使って明確に説明する
3. エラー発生時の状況を記載しない - エラーと解決策をドキュメント化する
4. 古い例を載せる - コードを定期的にテストして更新する
5. 用語に一貫性がない - ドキュメント全体で同じ用語を使う
6. 前提条件が不足している - すべての要件を最初に列挙する
7. 書式が適切でない - 見出し、リスト、コードブロックを適切に使う
8. 例がない - 常に動作するコード例を含める
9. 読者のレベルに合っていない - 読者に合わせて技術的な深さを調整する
10. 文章が詰め込まれている - 明確な見出しを使い、流し読みしやすいセクションに分ける

参考ファイル

• documentation-types-and-workflows.md - API ドキュメント、ユーザーガイド、チュートリアル、アーキテクチャドキュメント、技術仕様書の完全なテンプレートとパターン
• writing-guidelines.md - 明確さ、能動態、具体性、一貫性、見出しの階層、コードの書式設定、リストに関する詳細なスタイルルール