Webドキュメンテーション執筆スキル

ユーザーが単なる「コードの周辺テキスト」ではなく、Webプロジェクトの優れたテクニカルドキュメンテーションを求めている場合に、このスキルを使用します。仕事は、読みやすく、スキャンしやすく、信頼でき、保守しやすいドキュメンテーションを制作することです。

優れたドキュメンテーションは、製品の事実の羅列ではありません。特定の目標を持つ読者のための、製品を通じたガイド付きパスです。

このスキルが最適化する項目

1. 初回の迅速な成功 新しい読者が迅速に動作する結果に到達できること。

2. 意図による明確なルーティング 製品を学び始めた初心者と、オプションを確認する専門家が同じページで苦労すべきではない。

3. 低い曖昧性 コマンド、ファイル名、バージョン、前提条件、期待される結果、失敗状態は明示的であるべき。

4. スキャン可能性 多忙な開発者は読む前にざっと目を通します。見出し、導入、リスト、表、コードブロックはページを一目で操作可能にするべき。

5. 保守性 ドキュメンテーションは優雅に老化し、コード変更と共に更新しやすく、陳腐化した情報を明白にするべき。

非目標

以下については最適化しないでください：

• ハイプ
• マーケティング言語
• 各ページにおけるすべての背景情報の網羅性
• 最初のドキュメンテーションでサポートされるすべてのバリエーションの表示
• 工夫された文体
• 説明が少ないコードの巨大なダンプ

まず最初に決める：このページはどのような種類か？

ページタイプを選択する前にドラフトを作成しないでください。ページタイプを区別したまま保つ。

README またはドキュメンテーションランディングページ

方向性とルーティングに使用。

• 回答：これは何ですか？誰のためですか？どこから始めますか？
• 短く保つ。
• 深い詳細は子ページに押し出す。

クイックスタート

動作する結果への最速ハッピーパスに使用。

• 1つのパス。
• 1つのメイン環境。
• 最小限の分岐。
• 明確な前提条件と目に見える成功状態。

チュートリアル

実行することで教えるために使用。

• 読者は意味のあるものを構築します。
• チェックポイントと要約を含める。
• 学習に十分な説明、百科事典的カバレッジには十分でない説明。

ハウツーガイド

1つの具体的な問題を解決するために使用。

• 読者がすでに基本を理解していることを想定。
• 背景理論ではなく、結果に焦点を当てる。

リファレンス

正確な事実の質問に答えるために使用。

• 構文、オプション、デフォルト、パラメータ、戻り値、イベント、エラー、制限、互換性。
• ドライで完全で、スキャンしやすい。

説明/コンセプトページ

メンタルモデルを構築するために使用。

• システムがこの方法で機能する理由。
• アーキテクチャ、トレードオフ、不変量、決定ルール。
• タスクドキュメンテーションとリファレンスドキュメンテーションへのリンク。

トラブルシューティングページ

症状で問題を診断するために使用。

• 症状 → 予想される原因 → 修正 → 検証 → 予防。

マイグレーションガイド

バージョン、API、またはアーキテクチャが変更される場合に使用。

• 破損を明示的にする。
• 前後を表示。
• 安全な操作順序を提供。
• 関連する場合はロールバックガイダンスを含める。

デフォルトワークフロー

ユーザーがより狭い内容を求めない限り、このワークフローに従います。

1) 読者とジョブを特定する

推測または陳述：

• 読者タイプ：初心者、経験豊富なユーザー、メンテナー、インテグレータ、APIコンシューマー、プラットフォームエンジニア
• タスク：学習、セットアップ、統合、カスタマイズ、デバッグ、マイグレーション、デプロイ、貢献
• 環境：フレームワーク、ランタイム、パッケージマネージャー、OS、ブラウザ、ホスティングターゲット
• 成功状態：読者が終了後にできるようになるべきこと

重要な事実が欠落している場合、永遠にブロックしないでください。最も狭い合理的な仮定を立てて、それを明確に表示します。

2) 散文の前に事実を整理する

しばしば陳腐化する事実を収集：

• パッケージ名
• インストールコマンド
• ランタイムとフレームワークのバージョン
• サポートされているブラウザまたは環境
• 環境変数
• URL、エンドポイント、ポート、コールバックパス
• 権限、認証要件、キー、トークン
• ビルド、テスト、デプロイコマンド
• 破損する変更または制約

事実を検証できない場合、それを発明することは避けます。明確にマークされたプレースホルダーまたは仮定を使用します。

3) ページスケルトンを最初に構築する

完全な段落を書く前に、ページが必要とする正確なセクションを含むスケルトンを作成します。

推奨順序：

• コンテキスト
• 前提条件
• ステップまたは本文
• 検証/期待される結果
• 次のステップ/関連ページ

4) 最初の成功した実行のために書く

すべてのタスクページは、読者が可能な限り早く1つの成功した結果を得るのを助けるべき。

これは以下を意味します：

• 最短の動作パスを前面に配置
• 分岐を最小化
• 高度なオプションを遅延
• プロジェクトが複数の一流エントリポイントを真に支持していない限り、1つのパッケージマネージャーと1つのフレームワークを優先
• 成功がどのように見えるかを表示

5) 実行可能な例を作成する

例はコピー貼り付けまたは適応しやすいものである必要があります。

• 実際のファイル名と現実的なディレクトリを使用。
• コードフェンスにラベルを付ける。
• 例は最小限だが完全。
• コメントを追加するのは、曖昧性を取り除く場合のみ。
• コマンドが破壊的または課金の対象である場合、最初に警告します。
• 重要なステップの後に期待される出力または目に見える結果を表示。

6) 散文を引き締める

ドラフトが存在した後：

• 導入を短縮
• 長い段落を分割
• あいまいな見出しをタスクベースの見出しに変換
• 重複した説明を削除
• 手順的なページから理論を移動
• ランディングページから詳細を移動

7) レビューチェックリストを実行する

配信前に assets/review-checklist.md を使用します。

リファレンスファイル

現在のタスクに基づいて必要に応じて読み込む：

リファレンス	目的
references/house-style.md	音声、文の様式、見出し、長さのターゲット、ページタイプパターン
references/web-project-rules.md	Web プロジェクトチェックリスト、コード例ルール、アンチパターン、アクセシビリティ、ドキュメンテーション・アズ・コード
references/research-notes.md	強力なドキュメンテーションサイトとスタイルガイドからの研究統合

すべてのファイルを一度に読み込まないでください。 現在のタスクに関連するもののみを読み込みます。

一般的なタスクモードでの対応方法

ページを一から書くように求められた場合

配信内容：

1. 適切なページタイプ
2. 磨かれた Markdown ドラフト
3. 重要な事実が不明な場合、明確にマークされた仮定

既存のドキュメンテーションの改善を求められた場合

この順序で実行：

1. 現在のページタイプを特定
2. 混在したモードを削除
3. 構造を引き締める
4. 明確さのために書き直す
5. テクニカルな意味を保持
6. 事実的なギャップまたは陳腐化リスクを呼び出す

ドキュメンテーションをレビューするよう求められた場合

返却内容：

• ページタイプ
• 優先順位順の最大の問題
• 正確な書き直し提案
• 不足しているセクション
• 陳腐化または信頼の問題

ドキュメンテーションサイトを設計するよう求められた場合

返却内容：

• オーディエンスセグメント
• エントリポイント
• 必要なページタイプ
• サイトマップ
• オーサリングの優先順位
• ギャップとリスク

このスキルのファイル

• assets/documentation-brief-template.md — 執筆前に事実を収集
• assets/docs-ia-template.md — ドキュメンテーションサイトまたはセクションを構造化
• assets/docs-home-template.md — ランディングページスケルトン
• assets/readme-template.md — README スケルトン
• assets/quickstart-template.md — ハッピーパスセットアップガイド
• assets/tutorial-template.md — 学習バイドゥーイングガイド
• assets/how-to-template.md — タスク焦点ガイド
• assets/reference-template.md — API/リファレンススケルトン
• assets/explanation-template.md — メンタルモデルページ
• assets/troubleshooting-template.md — 症状優先トラブルシューティング
• assets/migration-guide-template.md — アップグレード/マイグレーションページ
• assets/review-checklist.md — 最終的な品質ゲート
• references/house-style.md — 音声、長さのターゲット、ページタイプパターン
• references/web-project-rules.md — Web プロジェクトチェックリスト、コードルール、アンチパターン
• references/research-notes.md — これらのルールが存在する理由

最終的な指示

最高のドキュメンテーションページは簡単に感じられます。なぜなら執筆者が読者のために100の慎重な選択をしたからです：

• このページに何が属するか
• 何が属さないか
• 何が最初に来るか
• 何を切り取るか
• 何を検証するか
• 何を説明するか
• 何を遅延させるか

これらの選択を意図的に行います。