documentation-writing

ドキュメント作成スキル

目的

Eight Rules と Diataxis フレームワークに従って、見つけやすく質の高いドキュメントを作成します。すべてのドキュメントが適切な場所に配置され、リンクされ、実際に実行できる例を含むようにします。

有効になるタイミング

次のような依頼をすると、自動的に読み込まれます。

• 「ドキュメントを書いて」または「ドキュメントを作成して」
• 「この機能／モジュール／APIをドキュメント化して」
• 「READMEを作成して」または「チュートリアルを書いて」
• 「これがどのように動くか説明して」
• Markdown ドキュメントの作成依頼全般

基本ルール（必須）

8つのルール

1. 配置場所：すべてのドキュメントを docs/ ディレクトリに置きます
2. リンク：すべてのドキュメントを、少なくとも1つの別のドキュメントからリンクします
3. 簡潔さ：平易な言葉を使い、不要な語句を削除します
4. 実例：「foo/bar」のようなプレースホルダーではなく、実行可能なコードを使います
5. Diataxis：1つのファイルにつき、ドキュメントの種類は1つにします（チュートリアル／ハウツー／リファレンス／解説）
6. 読みやすさ：説明的な見出しを使い、長いドキュメントには目次を設けます
7. ローカルリンク：相対パスを使い、リンクには前後の文脈を添えます
8. 最新性：古くなったドキュメントを削除し、更新メタデータを含めます

ドキュメントに含めないもの

docs/ に絶対に含めないもの：

• ステータスレポートや進捗報告
• テスト結果やベンチマーク
• 議事録や決定事項
• 日付を含む計画
• 特定時点のスナップショット

時系列情報の記載先：

• テスト結果 → CI ログ、GitHub Actions
• ステータス更新 → GitHub Issues
• 進捗 → Pull Request の説明
• 決定事項 → コミットメッセージ

クイックスタート

新しいドキュメントを作成する

# [Feature Name]

Brief one-sentence description of what this is.

## Quick Start

Minimal steps to get started (3-5 steps max).

## Contents

- [Configuration](#configuration)
- [Usage](#usage)
- [Troubleshooting](#troubleshooting)

## Configuration

Step-by-step setup with real examples.

## Usage

Common use cases with runnable code.

## Troubleshooting

Common problems and solutions.

ドキュメントの種類（Diataxis）

種類	目的	場所	ユーザーの質問
チュートリアル	学習	docs/tutorials/	「方法を教えてください」
ハウツー	実行	docs/howto/	「Xを行う方法を教えてください」
リファレンス	情報	docs/reference/	「どのような選択肢がありますか？」
解説	理解	docs/concepts/	「なぜこのようになっているのですか？」

ワークフロー

ステップ 1：ドキュメントの種類を決める

読者が何を達成しようとしているかを確認します。

• 新しいことを学ぶ → チュートリアル
• 特定の問題を解決する → ハウツー
• 詳細を調べる → リファレンス
• 概念を理解する → 解説

ステップ 2：配置場所を選ぶ

docs/
├── tutorials/     # Learning-oriented
├── howto/         # Task-oriented
├── reference/     # Information-oriented
├── concepts/      # Understanding-oriented
└── index.md       # Links to all docs

ステップ 3：例を使って書く

すべての概念に、実行可能な例が必要です。

# Example: Analyze file complexity
from amplihack import analyze

result = analyze("src/main.py")
print(f"Complexity: {result.score}")
# Output: Complexity: 12.5

ステップ 4：インデックスからリンクする

docs/index.md に項目を追加します。

- [New Feature Guide](./howto/new-feature.md) - How to configure X

ステップ 5：検証する

完了前のチェックリスト：

• ファイルが docs/ ディレクトリにある
• インデックスまたは親ドキュメントからリンクされている
• 時系列情報が含まれていない
• すべての例をテスト済みである
• Diataxis の種類を1つだけ扱っている

ナビゲーションガイド

補足ファイルを読むタイミング

reference.md - 次の情報が必要な場合に読みます。

• frontmatter の完全な仕様
• Diataxis の種類に関する詳細な定義
• Markdown のスタイル規約
• ドキュメントのレビューチェックリスト

examples.md - 次の情報が必要な場合に読みます。

• 各種類のドキュメントテンプレート全体
• 実際のドキュメント例
• 改善前後の例
• 複雑なドキュメントのパターン

避けるべきアンチパターン

アンチパターン	問題点	よりよい方法
「ここをクリック」というリンク	文脈がない	「認証設定を参照」
foo/bar の例	現実的でない	実際のプロジェクトコードを使う
長文の壁	要点を見つけにくい	見出しと箇条書きを使う
孤立したドキュメント	見つけられない	インデックスからリンクする
ドキュメント内のステータス	古くなる	Issues／PRs を使う

事後的なドキュメント作成の例外

実装前にドキュメントを書く場合（ドキュメント駆動開発）：

# [PLANNED - Implementation Pending]

This document describes the intended behavior of Feature X.

## Planned Interface

```python
# [PLANNED] - This API will be implemented
def future_function(input: str) -> Result:
    """Process input and return result."""
    pass
```

実装後は、[PLANNED] マーカーを削除し、実際の例に更新します。

---

**Full reference**: See [reference.md](./reference.md) for complete specification.
**Templates**: See [examples.md](./examples.md) for copy-paste templates.