| name | documentation |
| description | ドキュメント作成・改善を支援するスキル。新規ドキュメントの作成、既存文章の改善・レビュー、ドキュメント構成の設計を行う際に使用する。トリガー条件: ドキュメントやテキストの作成・執筆を依頼されたとき、文章の改善・レビューを求められたとき、ドキュメントの構成設計を相談されたとき。 |
Documentation
ドキュメント作成・改善を段階的に支援するスキル。
基本原則
- 見出しやタイトルは、書かれている内容が推測しやすい、簡潔で分かりやすい名前をつける
- 同じドキュメント内で見出しの命名スタイルを統一する（体言止め、動詞句など）
- 記述を共通化し、重複する内容は1箇所にまとめて参照リンクを貼る
ワークフロー分岐
ユーザの依頼内容に応じて、以下のいずれかのワークフローを選択する。
- 新規にドキュメントを作成する場合 → 「新規作成ワークフロー」
- 既存の文章を改善・レビューする場合 → 「改善・レビューワークフロー」
新規作成ワークフロー
以下の手順でドキュメントを作成する。
Step 1: 読み手とテーマの明確化（ユーザ確認必須）
ユーザに以下を質問し、ドキュメントの対象を絞り込む。
- テーマ（何について書くか）
- 読み手の目的（読み手は何を知りたいか）
- 読み手の知識レベル（初心者か経験者か）
- 読み手の立場（開発者、マネージャー、エンドユーザなど）
読み手とテーマが曖昧なままだと、ドキュメントが肥大化・複雑化するため、可能な限り絞り込む。
Step 2: テーマの階層構造への分解
テーマを複数のサブテーマで構成される階層構造に分解する。
- 全体から部分へ、概要から詳細へと段階的に情報を提供できる構造にする
- 分解の観点として「なぜ・何を・どうやって」を使う
- なぜ: なぜそれが必要なのか
- 何を: 何を実現したいのか
- どうやって: どのように実現するのか
例: ある機能を説明するドキュメントの場合
→ 概要、設定方法、利用方法、トラブルシューティング
Step 3: ドキュメント構成の設計
階層構造の各要素を見出しとして構成する。見出しは「見出しの基本原則」に従って命名する。
Step 4: 文章構成の設計
各見出しの中に書く文章の構成を組む。
- その見出しで伝えたいこと（topic sentence）を箇条書きで洗い出す
- 伝えたいこと同士の繋がりがよくなるように並べ替える
- 繋がりが悪い箇所があれば、橋渡しとなる文を書き足す
Step 5: 文の執筆
各topic sentenceに対して、読み手が納得できるよう理由や説明を書き足す。主な書き方として以下の3パターンがある。
- 理由を述べる（なぜなら〜だからです）
- 説明を述べる（〜とは〜のことです）
- 具体例を挙げる（例えば〜のような場合です）
執筆時は「文章品質基準」を遵守する。
Step 6: リード文の追加
タイトルや見出しの名前だけでは内容が把握しづらい場合、内容を補足するリード文を書く。前の見出しとの繋がりを改善する目的でもリード文を追加する。
改善・レビューワークフロー
Step 1: 文章の読み込み
既存の文章を読み込み、全体の構成と内容を把握する。
Step 2: 改善点の特定
「文章品質基準」と「見出しの基本原則」に照らして改善点を特定する。改善点は以下の分類で整理する。
- 構成の問題: 見出しの粒度、情報の順序、階層構造の適切さ
- 文章の問題: 1文1情報の違反、冗長な表現、主語と述語の距離
- 表現の問題: 否定形の多用、読み手の視点の欠如、曖昧な表現
Step 3: 改善案の提示
改善点ごとに以下の形式で提示する。
- 該当箇所: 問題のある文や見出し
- 問題: 何が問題か
- 改善案: 具体的な修正案
文章品質基準
両ワークフローで共通して適用する基準。
重要なことから書く
情報に優先度をつけて、優先度が高いものから書く。伝えたいことをまず述べ、その理由や説明は後に続ける。
読み手の視点で書く
著者の視点ではなく、読み手が理解しやすい視点で書く。
- 改善前: アプリの自動アップデートが有効になっていると、自動でアップデートの有無をチェックし、自動的にアプリをアップデートします
- 改善後: アプリの自動アップデートを有効にすると、アプリが自動的に最新バージョンにアップデートされます
簡潔に書く
1文には1つの情報のみ含める。文はできるだけ短くする。
- 改善前: アプリの自動アップデートを有効にすると、アプリが自動的に最新バージョンにアップデートされ、常に最新の機能とセキュリティパッチを利用できます
- 改善後: アプリの自動アップデートを有効にすると、アプリが自動的に最新バージョンにアップデートされます。これにより、常に最新の機能とセキュリティパッチを利用できます。
肯定形を使う
否定形は意味が分かりづらくなることがある。肯定的な表現ができる場合は肯定形を使う。
- 改善前: アプリのアップデートは放置したままにしないでください。
- 改善後: アプリのアップデートはなるべく早く行ってください。
