開発者向けの手引きは誰が書く？｜AIに任せる範囲を決める

「つないでみたいという問い合わせが来るたびに、開発の担当がメールで3往復しています。手引きは公開しているのですが、そこに書いてあることを聞かれます」「AIに下書きを作らせたら、体裁は整っているのに、そのとおりに動かない箇所が残りました。動くかどうかは結局、自分で試すしかありませんでした」。——社外の開発者に読ませる文書を用意した会社では、この2つがだいたい同じ時期に出てきます。開発者向けの手引きは、仕様を丁寧に書き写した文書ではありません。本当は、自社の担当者が立ち会わなくても、相手が最後までたどり着けるようにするための体制の代わりです。だから手引きが薄いほど、足りない分を人の時間で埋めることになります。API開発ツールの提供元が2025年に公開した調査（回答者5,700人超）では、開発者の69%が週10時間以上をAPI関連の作業に充てており、4分の1を超える人が週20時間以上と答えています。問い合わせ対応は、この上に乗ります。この記事では、手引きに何を入れ、誰が書き、どこまでAIに任せ、古くなった記述をどう扱い、何で良し悪しを測るかを、体制と費用の判断まで含めて整理します。

手引きが薄いと、開発の時間が問い合わせに溶ける

API開発ツールの提供元が毎年出している調査の2025年版（第7回・回答者5,700人超、うち73%がエンジニアやソフトウェア開発の職種）では、APIに関わるチームの93%が連携上の何らかの障害を抱えており、最も多かったのがドキュメントの不整合で55%でした。以下、既存のAPIを見つけられない、同じものを重ねて作ってしまう、と続きます。2023年版でも、開発の妨げとして「ドキュメントの不足」を挙げた開発者が52%います。年が変わっても、上位の顔ぶれが入れ替わっていません。

手引きが薄いと何が起きるか。読み手は書いていないことを人に聞きます。問い合わせが窓口に届き、答えられるのは作った本人なので開発の担当に回り、返信を書き、相手が試し、また質問が来る。1件で2往復から3往復になります。この往復の中身は、多くが手引きに書けたはずのことです。しかも返した内容はその相手にしか残らないので、次の相手が同じ場所でつまずけば、同じ返信をもう一度書くことになります。

費用として見えにくいのは、この時間がどの科目にも載らないからです。問い合わせ対応は誰かの予定表に「対応」としか残らず、月末に集計されません。先の調査の数字と重ねると、API関連の作業に週10時間以上を使っている開発者の時間から、さらに問い合わせの分が引かれている計算になります。減っているのは、製品を作るほうの時間です。

逆から見ると、手引きは読み物ではなく問い合わせを前倒しで処理する仕組みだと分かります。書いてある1行が、これから来る何十件かの質問を先に消します。どの1行を先に書くかは、これまでに来た質問を並べれば決まるので、新しく構成を考える必要はありません。手引きの企画で最初にやることは、執筆ではなく件数の集計です。

社内のマニュアルと、社外の開発者が読む手引きは別物

同じ「手順を書いた文書」でも、社内向けと社外向けでは前提が3つ違います。1つめは、読み手に聞ける相手がいるかどうかです。社内なら隣の席や相談先に聞けるので、書いていないことは口頭で埋まります。社外の開発者には聞く先がないか、聞くのに手続きと待ち時間が要ります。書いていないことは、そのまま止まるという前提で設計します。

2つめは、前提がそろわないことです。社内であれば、使っている環境も用語も共通しています。社外の読み手は、言語も、動かす場所も、名前の付け方も違います。社内の文書で省略されがちな「どこで動かす前提か」「何が入っていれば動くか」を、省略せずに先頭で書く必要があります。ここを省くと、動かない原因の切り分けが読み手の側でできません。原因が分からない問い合わせは、往復の回数がいちばん多くなります。

3つめは、間違いの直し方です。社内の手順書なら、誤りに気づいた人がその場で直せます。社外に出した手引きは、誤った記述のまま実装された仕組みが相手側で動き続けます。直すには、告知と、相手側の作業と、待ち期間が要ります。直す費用が自社の外に出てしまうのが、社外向けの文書の特徴です。

この3つから、作り方が変わります。社内マニュアルの作法をそのまま持ち込むと、聞けば分かる前提で書かれた箇所が残ります。持ち込んでよいのは、更新の当番を決める、改訂の記録を残すといった運営の部分だけです。中身の設計は別の物差しで作り直します。作り直す物差しが、次に挙げる6つの要素です。

手引きに入れる6つの要素と、抜けたときに起きること

公開されている手引きを並べて比べると、入れる要素は6つに収束します。始め方の道筋、認証の通し方、戻り値と失敗時の応答、制限値、変更の履歴、実際に動く例です。並べる順番にも意味があります。読み手は上から順に読まず、詰まった場所から探しに来るので、詰まりやすい順に置きます。

要素	読み手が知りたいこと	抜けたときに起きること
始め方の道筋	登録から最初の1回までに何をすればよいか	検討の段階で離脱する。試す前に問い合わせが来る
認証の通し方	鍵の取り方、置き場所、期限、試験用と本番の分け方	最初の1回に届かない。期限切れのたびに同じ質問が来る
戻り値と失敗時の応答	何が返るか、失敗したとき次に何をすればよいか	総当たりで試される。無駄な再試行が制限値に当たる
制限値	回数、大きさ、同時数、保存される期間の上限	設計をやり直すことになる。本番直前に問い合わせが集中する
変更の履歴	いつ何が変わり、自分の実装は影響を受けるか	動かなくなった原因が分からず、障害として報告される
実際に動く例	写して動かせる最小の一式と、返ってくる中身	説明が正しくても信用されない。全項目を疑われる

右の列は想像で書いたものではなく、問い合わせの内容をそのまま裏返したものです。自社に届いた質問を3か月分並べ、どの要素の欠落に当たるかを分類すると、どれが抜けているかが件数で出ます。全部を一度に整えようとせず、件数の多い要素から手を入れます。件数の順に手を入れると、1項目直すごとに問い合わせが目に見えて減るので、続ける理由が社内でも説明しやすくなります。

逆に、入れなくてよいものもあります。会社案内、製品の思想、他社との比較。これらは読み手が別の場所で読むもので、手引きに混ざると、探している1行までの距離が伸びます。手引きの中では売り込みの文面を持たない、という線を引いておくほうが、結果として相手の導入は速くなります。

始め方の道筋は、最初の1回が返るまでの時間で決まる

手引きの出来を1つの数字で表すなら、読み始めてから最初の呼び出しが成功して返ってくるまでの時間です。API開発ツールの提供元の開発者向け責任者が2021年に提唱した考え方で、探し始めてから最初の1回が返るまでを測ります。摩擦の原因として挙げられているのは、文書の質と構成、登録の手続きの長さ、始め方の案内の不明確さ、そして最初は見えない実装の複雑さです。

技術文書の制作会社が2025年7月に公開し、2026年7月に更新した記事では、この時間の目安を4段階に置いています。2分未満なら良好、2分から5分なら及第、5分から10分は要改善、10分を超えると危険信号という分け方です。同じ記事では、手続きに摩擦が生じた場合の初期段階での離脱が5割から7割に達するという整理も紹介されています。文書が最初の疑問に答えられないと半数が離れる、という別の指摘も併せて引かれています。

測り方は単純です。3つに分けて記録します。

1. 登録してから、呼び出しに使う鍵が手元に届くまでの時間
2. 始め方の案内を開いてから、最初の呼び出しを投げるまでの時間
3. 最初の呼び出しが成功して、想定どおりの中身が返るまでの時間

自社で測るときは、作った本人ではない人に、手引きだけを見て試してもらいます。作った本人は書いていないことを知っているので、必ず速く終わります。営業の担当、入社したばかりの技術者、取引先の開発者。3人に同じことをしてもらい、止まった場所と、その場で何を検索したかを記録します。止まった場所が3人とも同じなら、そこが最初に直す1か所です。ここに時間をかけずに全体の網羅を進めても、離脱する人の数は変わりません。

認証と失敗時の応答は、うまくいかない場合こそ書く

認証は最初の1回の前に必ず通る場所なので、ここで止まると全部が止まります。にもかかわらず、手引きの認証の項目は、うまくいった場合の手順だけで終わっていることが多いです。鍵の取り方、鍵をどこに置くか、有効期限があるか、試験用と本番用が分かれているか、期限が切れたときに何が返るか。この5つのうち後ろの3つが抜けている、というのがよくある形です。

失敗時の応答も同じで、コードの一覧だけでは足りません。読み手が知りたいのは、何が起きたかではなく次に何をすればよいかです。失敗の説明は、原因と、読み手の次の一手をひとまとめに書く。並べてみると、足りない書き方の特徴がはっきりします。

• 認証に失敗しました。認証情報をご確認ください（何を確認するのかが書かれておらず、鍵の値か置き場所か期限かが分からない）
• 不正なリクエストです（どの項目が不正なのかが返らないので、読み手は総当たりで試すことになる）
• しばらく待ってから再度お試しください（待つ時間の目安がなく、再試行してよい失敗かどうかも分からない）
• 内部エラーが発生しました（自社に問い合わせる以外の道が残らない。件数がそのまま窓口に乗る）

書き直すと、原因の候補、読み手が確認する場所、再試行してよいかどうか、待つ時間の目安、それでも直らないときの連絡先、という順になります。再試行してよい失敗と、してはいけない失敗を分けて書くのが要点です。ここが曖昧だと、相手の仕組みが同じ呼び出しを繰り返し、制限値に当たり、そこからさらに別の問い合わせが生まれます。1つの曖昧さが2件の問い合わせになる、という増え方をします。

認証の項目には、試験用の環境をどう使うかも書きます。本番の鍵しか発行できない作りだと、読み手は本番で試すことになり、失敗の跡がこちらの記録に残ります。試験用の鍵をその場で発行できるかどうかは、文章の巧拙より効きます。先に挙げた制作会社の記事でも、時間を縮める要素の筆頭に鍵の自動発行が挙げられています。

制限値と課金に関わる記述は、最後まで人が確かめる

制限値は、書いていないと必ず問い合わせになる項目です。単位時間あたりの呼び出し回数、同時に走らせてよい数、1回で送れる大きさ、保存される期間、一覧で返ってくる件数の上限。読み手はこれを設計の前に知りたいので、後ろの参考資料ではなく、始め方の次に置きます。設計が終わってから知ると、作り直しになります。

制限値の記述は、実装と一致していないことがあります。実装を変えたのに手引きだけが古い、あるいは手引きが正しくて実装のほうが緩い。どちらの向きでも問題ですが、緩いほうが厄介です。読み手は書いてあることより実際の動きを信じるので、書いてある制限値より緩く動いていれば、その緩さが仕様として使われます。後から締めると、相手の仕組みが止まります。

課金に関わる記述は、さらに重い扱いにします。何を1件として数えるか、失敗した呼び出しは数えるか、再試行は数えるか、無料の範囲はどこまでか。ここを1文字間違えると、相手の請求額が変わります。課金の記述は経理と契約の担当が読んで承認した文面だけを載せる、という決めを先に置きます。承認の記録が残っていない文面は載せない、というところまで決めておくと、急いでいる日にも抜けません。

• 制限値と課金の記述は、AIに下書きを作らせてよい箇所ではありません。実装の設定値と料金表の両方を人が見て、一致を確認したうえで書き写します
• 数値を更新したときは、手引きの更新日と、どの版から適用されるかを併記します。日付がないと、読み手は自分が読んでいる記述がいつのものか判断できません

制限値と一緒に書いておくと問い合わせが減るのが、制限に当たったときの挙動です。呼び出しが拒否されるのか、待たされるのか、順番待ちに入るのか。挙動が分かれば、相手は自分の側で対処を組み込めます。分からなければ、こちらに聞くしかありません。上限の数値だけを書いて挙動を書かない手引きは、数値を書いた分の効果を半分しか回収できていません。

実際に動く例を1つ置く。読む手引きから、動かす手引きへ

手引きの中で最も読まれるのは、説明文ではなく例です。読み手は例を写して動かし、動いてから説明を読みに戻ります。だから例が動かない手引きは、説明が正しくても信用されません。1か所でも動かないと、読み手は残り全部を疑い始め、確認のための問い合わせが増えます。

先に挙げた制作会社の記事でも、時間を縮める要素として、鍵の自動発行、その場で実行できる形のコード、鍵と例のデータが入った写して使える断片、最初の10分に絞った始め方の案内が挙げられています。例の作り方に落とすと、次のような形になります。

• 写したらそのまま動く例を、最初の1回ぶんだけ用意する。応用は後ろの章に回す
• 例に使う言語は、読み手の多い順に2つか3つまで。増やすほど、全部を最新に保てなくなる
• 例の中の値は、本物に近い形にする。省略の記号だけが並ぶ例は、そのまま実行できない
• 成功したときに返ってくる中身も、例の直後に並べる。何が返れば正解かが読み手に分かる

例の数は増やしたくなりますが、増やすほど古びる速度が上がります。例は資産ではなく負債として数えます。1つ増やすたびに、版が変わるたびの確認が1つ増えます。動作を確かめる仕組みに載せられない例は、原則として置かない。この線引きをしておかないと、半年後には動かない例が並ぶことになります。

動作の確認を自動で回す作りにできるなら、手引きの信頼はそこで担保されます。大手の技術部門が公開した記事でも、仕様やソースから中間の形式を作って出力を生成し、継続的に統合する仕組みで自動更新する進め方が紹介されています。2019年の記事ですが、考え方は今も変わっていません。例が壊れたら気づける形にしてから、例を増やすという順番です。

誰が書くか。3つの置き方を比べる

書き手の置き方は3つあります。開発者本人が書く、専任の書き手が書く、営業と技術の間に立つ人が書く。どれか1つが正しいのではなく、いま何が足りていないかで選びます。足りないものが違えば、答えも違います。

開発者本人が書く

正しさは最も高くなります。実装を知っている人が書くので、制限値も失敗時の応答もずれません。限界は2つです。時間が取れないことと、読み手の前提が見えないこと。知っている人は、知らない人がどこで詰まるかを想像しにくい。結果として、正しいけれど最初の1回にたどり着けない手引きができます。開発の合間に書くため、忙しい時期に優先度が下がって止まる点も、置き方の弱点として織り込んでおきます。

専任の書き手が書く

読み手の前提に立った構成が作れます。ただし、書き手が文章を書いている時間は思うより短いです。大手の技術部門が公開した記事では、テクニカルライターが実際に文章を書いている時間は全体の約1割で、残りの9割は開発者への聞き取りや、他の人が書いた文書の確認に充てられると説明されています。1人置けば書き上がるわけではなく、聞き取りに応じる開発者の時間が必ず要ります。この時間を見込まずに採用すると、書き手が待ち時間で遊ぶことになります。

営業と技術の間に立つ人が書く

導入の場に立ち会っている人が書くと、実際に聞かれた質問がそのまま項目になります。読み手の詰まりどころには強い一方、実装の細部は本人では確かめられません。確認の往復が増えるので、確かめる相手を1人に決めておく必要があります。相手が決まっていないと、聞く先を探す時間のほうが長くなります。

選び方の目安はこうです。正しさが足りていないなら開発者本人、たどり着けなさが問題なら専任の書き手、そもそも何を聞かれているか分かっていないなら間に立つ人。同じ記事の中でも、始め方の道筋は間に立つ人、制限値は開発者本人、という分け方ができます。書き手は文書の単位ではなく、項目の単位で割り当てると、3つの置き方は択一ではなくなります。

外部に出す選択もあります。効くのは、構成の作り直しと、既にある記述の整理です。外部の書き手に実装の正しさまで持たせることはできないので、確認の役だけは社内に残します。ここまで渡すと、誰も正しさを持たない文書ができあがります。外に出すのは作業で、社内に残すのは責任だと分けておくと、見積もりの内訳も説明しやすくなります。

AIに任せる作業と、任せない作業を、作業名で線を引く

「最終的には人が確認する」という一文は、運用に落ちません。落とすには、作業の名前で分けます。集める・整えるはAI、確かめる・決めるは人。この2つで仕分けると、どの作業がどちらに属するかで迷わなくなります。表にして、項目ごとに埋めておきます。

作業	任せ方	その理由	人が確かめること
項目ごとの説明を、決めた型で埋める	AIに渡す	書式が決まっていて、判断が入らない	埋まった内容が実装と合っているか
開発者のメモを、読み手向けに言い換える	AIに渡す	内容を足さず、並べ替えと平易化だけを行う	言い換えで意味が変わっていないか
用語と表記を全体でそろえる	AIに渡す	機械的な突き合わせの作業	そろえた用語が社内の呼び方と一致するか
翻訳の下訳を作る	AIに渡す	用語集を固定すれば品質が安定する	製品固有の語と、契約に関わる語
抜けている項目を洗い出す	AIに渡す	型と本文を突き合わせるだけ	洗い出しの対象そのものに漏れがないか
書いた手順どおりに動くかを確かめる	人が持つ	実際に動かさないと分からない	手順の全部
制限値と課金の数値を書く	人が持つ	間違えると相手の請求と設計が変わる	設定値と料金表との一致
廃止と移行の告知文を出す	人が持つ	日付と対象が契約上の意味を持つ	日付、対象、移行先の3点

表を作ったら、渡す側の指示にも同じ言葉を使います。「読みやすくして」ではなく「この型のこの項目を、この材料だけで埋める。材料にない事柄は空欄のまま残す」。材料にないことは埋めさせず、空欄で返させる。空欄で返ってくるのは失敗ではなく、人が確かめる箇所が見えたということです。

空欄の指示を入れないと、それらしい数値や手順が入ります。入ってしまうと、後の工程では誰かが書いた記述として扱われ、確認の対象から外れます。手引きの事故は、間違った記述そのものよりも、確認されないまま通った記述から起きます。空欄の数を毎回数えておくと、どの項目で材料が足りていないかも見えるようになります。

AIの下書きが通らないのは、確かめる人を決めていないから

AIに下書きを作らせて止まる場面は、だいたい同じ形をしています。体裁は整い、章立てもそろっている。ところが、書いてあるとおりに動かない箇所がいくつか残る。どこが残っているかは全部を試すまで分からない。結果として、確かめる時間が書く時間より長くなります。短縮したはずの工程が、後ろで戻ってきている状態です。

これを短くするには、出力に根拠を付けさせます。付けさせる項目を先に固定しておくのが要点です。

• その記述の元にした資料の名前と、該当する箇所
• 実装から読み取った値か、人から聞いた値か、どちらでもない推測か
• 確かめられていない箇所（動作を試していない手順、出どころのない数値）
• 前の版から変えた箇所と、変えていない箇所

根拠が付いていれば、確かめる範囲を絞れます。推測と書かれた行だけを試せばよく、全部を試す必要がなくなります。出どころに答えられない記述は、載せないという基準を先に決めておきます。基準がないと、疑わしい行を毎回その場で議論することになり、議論の時間のほうが確認より長くなります。

もう1つ、自動で入った記述と人が書いた記述が、後から見分けられる形にしておきます。社内の確認用の版だけでかまいません。見分けがつかないと、確認する人は全部を疑うか全部を信じるかの二択になります。前者は時間が増え、後者は誤りが外に出ます。どちらの経路で誤りが起きたかを数えられるようになると、任せる範囲を広げるか狭めるかの判断も、感覚ではなく件数でできます。

版が変わると古びる。古い記述を残すか消すかの決め方

手引きが信用を失うのは、間違っていたときよりも、古いままだったときです。読み手は、書いてある内容と実際の動きが違うと気づいた時点で、文書を読むのをやめて人に聞き始めます。ここで問い合わせが戻ってきます。整備の効果が半年で消えるのは、たいていこの経路です。

古い記述の扱いは、3つに分けて決めておきます。

1. 今も動くが推奨しない記述 … 残す。推奨しない旨と、代わりに何を使うかを同じ場所に書く
2. もう動かない記述 … 残す。いつ止まったかと移行先を書く。消すと、古い実装を持っている読み手が行き先を失う
3. 最初から誤っていた記述 … 消す。訂正した旨と訂正日を、変更の履歴に残す

動かなくなった記述を黙って消すのが、いちばん問い合わせを増やします。読み手は自分の手元の実装を基準に探しに来るので、記述ごと消えていると、そもそも何が起きたのかが分かりません。残したうえで止まった日と移行先を書けば、そこで自己解決します。残す判断は、量を増やす判断ではなく、問い合わせを減らす判断です。

版を変えるときの予告も、手引きの一部です。いつ告知し、いつまで両方が動き、いつ古いほうを止めるか。これを日付で書きます。期間の長さは相手の実装の重さで決めます。数行の直しで済むなら短くてよく、設計の作り直しが要るなら長く取ります。相手の作業量を見積もらずに期間を決めると、期限の直前に延長の依頼が集中します。

• 予告の期間と告知の方法は、契約や利用規約で定めている場合があります。手引きに書く前に、自社の規約の記載と一致しているかを法務の担当と確認してください
• 移行先が決まっていない段階で廃止の日付だけを告知すると、問い合わせが集中します。移行先の記述が完成してから告知します

AIが手引きを読む側に回る、という新しい前提

ここ1年ほどで前提が1つ増えました。手引きを読むのが人だけではなくなっています。開発者が使う道具に生成AIが組み込まれ、実装を書く場面で手引きの内容が参照されます。先の調査でも、開発者の89%が日常の業務で生成AIを使っているという結果が出ています。

一方で、AIが利用する側に回ることを想定してAPIを設計している組織は24%にとどまり、60%は人だけを想定した設計だという結果も、同じ調査に出ています。読み手の構成が変わっているのに、書き方が追いついていないという状態です。ここは差がつきやすい場所でもあります。

実務の対応は、派手なことではありません。生成AIに読ませることを想定した案内用のテキストを入口に1つ置く、文書を機械が読みやすい形でも返す、といった進め方が、開発者向けの文書作成の道具を提供する事業者から2026年にかけて相次いで示されています。いずれも人向けの手引きが整っていることが前提で、整っていない内容を機械向けに出しても結果は変わりません。順番を飛ばさないことが要点です。

気をつけるのは、AIが読んだ結果をこちらが確かめられないことです。誤った記述が残っていると、それが実装に写され、こちらに届く前に動いてしまいます。誤りが人の目を経ずに広がる経路が1本増えたと考えて、制限値と課金の記述の点検を先にやっておきます。人が読む前提なら「おかしい」と気づいて問い合わせが来ましたが、その気づきの機会が減っています。

手引きを立ち上げる順番と、途中で止まる型

順番を間違えると、量は増えたのに問い合わせが減らない、という結果になります。先に手を付けるのは、全体の網羅ではなく、最初の1回までの道です。

途中で止まる型は4つあります。どれも書き手の能力ではなく、置き方の問題です。

• 網羅から作り始める。全項目を埋める計画を立てると、最初の1回までの道が最後まで完成しない
• 書き手を決めずに、手が空いた人が書く。誰の作業でもないので、忙しい時期に必ず止まる
• 確認を作った本人が行う。書いていないことを知っている人が試すため、詰まりどころが見つからない
• 実装の変更と手引きの更新を別の作業として扱う。片方だけが進み、数か月で記述と動きがずれる

直し方はそれぞれ1行で書けます。最初の1回までの道を先に完成させる。書き手を項目ごとに名前で決める。確認は本人以外の3人に回す。実装を変える作業の中に、手引きを直す手順を入れる。どれも道具を入れる前に決めることです。決めずに道具を入れると、道具を替えるたびに同じ議論をやり直すことになります。

手引きの良し悪しは、何で測るか

読まれた回数だけでは分かりません。読まれていても、読んだ後に問い合わせが来ているなら、その頁は役に立っていないからです。測るのは4つです。

• 最初の1回が返るまでの時間（登録してから、最小の呼び出しが成功するまで）
• つなぎ終わるまでの日数（契約や試用の開始から、相手の環境で動き始めるまで）
• 問い合わせの件数（手引きに書いてある内容の質問と、書いていない内容の質問を分けて数える）
• 同じ質問の繰り返しの回数（同じ内容が月に何件来ているか）

書いてある内容の質問と、書いていない内容の質問を分けて数えるのが要点です。前者が多いなら、内容ではなく探しにくさの問題なので、並び順と見出しを直します。後者が多いなら項目そのものが足りていないので、書き足します。分けずに総数だけを見ると、どちらの手当てをすればよいかが決まりません。分類は問い合わせの窓口で付ける決まりにしておくと、後から遡る手間が消えます。

つなぎ終わるまでの日数は、営業の側の数字とつながります。試用が始まってから動き始めるまでが長いほど、商談は止まったまま時間が過ぎます。この日数は、手引きを直すと最も早く動く数字です。1件ずつの事情に左右されるので、同じ型の案件を10件そろえて前後で比べます。全案件の平均で見ると、難しい案件が混ざって読めなくなります。

読み方も先に決めておきます。問い合わせの件数が減らないのに日数が縮んでいるなら、効いているのは始め方の道筋です。続けます。件数は減ったのに日数が変わらないなら、詰まっているのは手引きではなく、鍵の発行や契約の手続きです。ここは文書では直りません。数字が2つ動いたときにどちらを優先するかを先に書いておくと、3か月後の判断で止まらずに済みます。

手引きの質が、導入の速さと問い合わせ対応の人数を決める

ここまでは文書の話に見えますが、決裁の場で判断するのは体制と費用です。手引きの質は、2つの数字に直接つながります。導入が終わるまでの日数と、問い合わせに何人を張り付けるか、の2つです。

人数のほうから見ます。手引きに書いていない項目が1つあると、その項目について問い合わせが来続けます。1件あたり2往復、1往復が開発者の30分だとすると、月に20件で20時間。これで開発者の0.1人月を超えます。項目が5つ抜けていれば0.5人月です。抜けた項目の数が、そのまま問い合わせ対応に張り付く人数になります。専任の書き手を1人置く費用と、この人数を並べれば、どちらが重いかは自社の件数で計算できます。

日数のほうも同じです。相手の環境で動き始めるまでが2週間か2か月かで、商談に張り付く期間が変わります。導入が長引く分だけ、営業と技術の担当が同じ案件に拘束されます。1人の担当が同時に持てる案件の数は、導入にかかる日数で決まります。手引きを直すと、この数が動きます。売上の側から見ると、人を増やさずに扱える案件が増える、という形で効きます。

判断の順番としては、まず件数を数え、次に人数に換算し、それから置き方を決めます。件数が少ない段階で専任の書き手を置くと余ります。件数が増えてから置くと、その間の問い合わせを開発者が受け続けます。目安としては、同じ質問の繰り返しが月に10件を超えたら、書き手の置き方を決める時期です。数えていれば、この判断は感覚ではなく数字でできます。

外部に出すかどうかも、同じ物差しで測れます。構成の作り直しと既存の記述の整理は外に出せます。実装の正しさの確認と、制限値や課金の記述は社内に残ります。見積もりを取るときは、この分け方で内訳を作ってもらうと比較ができます。一式で見積もりが返ってくる場合は、確認の役が誰にあるかが決まっていない合図なので、そこを先に詰めます。

よくある質問

手引きは日本語と英語のどちらを先に作るべきですか

読み手の多いほうを先に作り、もう一方は下訳をAIに作らせて人が確かめる順番が現実的です。両方を同時に作ると、片方が必ず遅れて、どちらが正しいか分からない状態になります。どちらを正とするかを先に決めます。正のほうを直してから、もう一方を追従させる。用語集を先に固定しておくと、下訳の手直しは大きく減ります。

AIが作った下書きは、どれくらい直すことになりますか

直す量よりも、確かめる量のほうが問題になります。型と材料を渡した場合、文章としての手直しは多くありません。ただし、動くかどうかの確認は記述の数だけ発生します。作る時間が減っても、確かめる時間は減りません。AIを入れる前に、確かめる担当と時間を先に確保してください。確保しないまま入れると、確認を飛ばした記述が外に出ます。

手引きを整えると、問い合わせはどれくらい減りますか

一般的な削減率を当てにしないほうがよいです。減り方は、いま何が抜けているかで大きく変わります。自社で見るなら、手を入れる前の3か月と後の3か月で、同じ分類の問い合わせ件数を比べます。比べるのは総数ではなく、手当てした項目の件数です。総数で見ると、利用者が増えた分と相殺されて動きが読めません。

開発者が書く時間を確保できません。どこから始めればよいですか

開発者に文章を書かせず、話してもらう形から始めます。問い合わせの多い項目について聞き取りの記録を取り、それを材料にAIが型を埋め、開発者は出来上がった記述が正しいかどうかだけを見る。書く作業から確かめる作業に変えると、1項目あたりの拘束時間が大きく下がります。ただし、聞き取りに応じる時間までは、なくせません。ここは予定に入れておきます。

まとめ

開発者向けの手引きは、仕様を書き写した文書ではなく、自社の担当者が立ち会わなくても相手が最後までたどり着けるようにするための、体制の代わりです。入れる要素は6つ。始め方の道筋、認証の通し方、戻り値と失敗時の応答、制限値、変更の履歴、実際に動く例。抜けた項目の数だけ問い合わせが来ます。書き手は文書の単位ではなく項目の単位で割り当て、開発者本人、専任の書き手、営業と技術の間に立つ人を、足りていないものに合わせて選びます。AIに渡すのは、型を埋める、言い換える、表記をそろえる、下訳を作る、抜けを洗い出すまで。動くかどうかの確認、制限値、課金、廃止の告知は人が持ちます。材料にない事柄は埋めさせず、空欄のまま返させます。

古くなった記述は、動かなくなったものほど残して、止まった日と移行先を書きます。測るのは、最初の1回が返るまでの時間、つなぎ終わるまでの日数、問い合わせの件数、同じ質問の繰り返しの回数の4つです。そしてこの4つは、そのまま体制と費用の話になります。抜けた項目の数は問い合わせに張り付く人数に、導入にかかる日数は1人が同時に持てる案件の数に変わります。手引きを整える作業は、文章を書く作業ではなく、何人で回すかを決める作業です。まず質問を3か月分数えて、最初の1回までの道から作り切る。この順番なら、増やした分量に見合っただけ問い合わせが減ります。

※本記事にはAIが活用されています。編集者が確認・編集し、可能な限り正確で最新の情報を提供するよう努めておりますが、情報の完全性、正確性、最新性、有用性等について保証するものではありません。本記事の内容に基づいて行動を取る場合は、読者ご自身の責任で行っていただくようお願いいたします。