自分が作ったツールは、自分には当たり前に見えます。ところが隣の人は、どこを押せばいいのかすら分からない。引き継ぎのたびに口頭で説明し直しているなら、書き物の側を整えるほうが早く直ります。Zapier の公式ブログも、良い文書は「読み手と目的が決まって初めて書ける」という立場で、構成の型と実例を解説しています。
書く前に「読み手」を1人に決める
文書が読みにくい最大の原因は、読み手が決まっていないことです。初めて触る人向けに書くのか、設定を変える担当者向けに書くのかで、載せる情報が変わります。引き継ぎ書なら、初めて触る人に限定してください。上級者向けの注意は、別の節に追い出せば足ります。
手順1：口頭の説明を録って、そのまま渡す
ツールの画面を開きながら、隣の人に説明するつもりで話し、その内容をテキストにしてAIに渡します。きれいに整える必要はありません。話し言葉のままの方が、どの部分を補足すべきかがAIにも伝わります。
手順2：読み手と目的をAIに宣言させる
「この文書の読み手は、ツールを触るのが初めての担当者です。目的は、担当者が休みの日に他の人が代わりに操作できるようにすることです」のように、前提を先に置いてから整文を依頼します。宣言がないと、AIは専門家向けの要約を作りがちです。
手順3：構成は「最初の1回・毎回・困ったとき」で分ける
| 節 | 載せる内容 | 目安 |
|---|---|---|
| 最初の1回 | アクセス方法、初期設定、用語 | 画面の数で3〜5枚に収める |
| 毎回 | 操作の手順、入力の例 | 手順は1行1動作で書く |
| 困ったとき | エラーの対処、問い合わせ先 | 実際に起きた事例だけ載せる |
この3つに分かれていない文書は、読む人が自分の位置を見失います。AIに整文させるときも、この3節の枠を指定すると崩れません。
手順4：用語の書き揺れを統一させる
「画面」「ページ」「ビュー」が混ざっていると、手順が追えなくなります。整文の依頼に「同じものを指す言葉は1つに統一し、統一した対照表を最後に付けてください」と入れます。対照表は、次に文書を触る人の点検道具にもなります。
手順5：手順どおりに一度やってみる
整った文書を、書いた人ではない人に渡し、文書だけを見て操作してもらいます。止まった場所に印を付けてもらい、その箇所だけを書き直します。ここで「口頭で補足したくなる」場所が、文書として欠けている場所です。
手順6：更新の入り口を1つに決める
文書が古くなる原因は、更新が面倒なことです。更新の依頼を受け付ける場所を1つに決め、変更が入ったらその場に書き込む。四半期に1回、AIに「この文書で、手順として矛盾している部分を指摘してください」と頼めば、点検の下地ができあがります。依頼文の書き方そのものは、プロンプトエンジニアリングの基本と重なります。
よくあるつまずき
AIに整文させると、実装の細かい話が消えて、ポジティブな紹介文に寄ることがあります。「操作の手順と、失敗したときの対処だけを残し、ツールの良さを説明する文は削ってください」と指示してください。引き継ぎ書に宣伝文は要りません。
FAQ
Q. 画面のキャプチャは必要ですか？
A. 最初の1回の節だけあれば足ります。手順の節は文字で追える形が理想です。画像は更新が追いつかず、古い画面のまま残りやすい弱点があります。
Q. 文書化にどこまで時間をかけるべきですか？
A. 目安は「隣の人が文書だけで最初の操作を終えられる」までです。完璧な文書を作ろうとすると更新が止まるので、最初は粗いまま運用に入れ、止まった箇所から直すほうが続きやすいです。
出典
出典：Zapier「API documentation: What it is and how to write it (with examples)」（2026年10月19日）
あわせて使いたいツール
本記事の手順を実際に回すときに、候補になるツールを挙げます。いずれも無料から試せる範囲があり、料金や機能は各サービスの公式情報で確認してください。
関連ガイド
同じ時期に公開した実務ガイドと、用語の定義ページです。手順の前提が分からない場合は、用語ページから確認してください。コピーして使える依頼文が欲しいときは、プロンプト集も参照してください。
編集部の見解
文書化を後回しにする理由の大半は、「書く才能がない」ではなく「書く時間が業務として確保されていない」だと思います。話す内容をそのままAIに渡して整えるなら、1本20分程度で形になります。引き継ぎは相手が変わるたびに起きるので、1回きりの説明で済ませようとするほうが、トータルの損失は大きいと感じています。
最新のAI情報をメールで受け取る
新着のAIツール比較・ランキング・ニュースを、まとめてお届けします。
ご登録後、確認メールをお送りします。配信停止はいつでも可能です。