はじめに
正直に言うと、ドキュメントの手入れって、うちのチームでもずっと後回しでした。
書くところまでは、みんなちゃんとやるんです。困るのはそのあと。半年も経つと、どれが今の仕様でどれが過去の話なのか、書いた本人ですら即答できなくなります。
実際に起きていたのは、こんなことでした。
- 新しく入った人が、更新の止まったページを読んで実装してしまう
- 同じ設定の説明が2か所にあって、書かれている値が食い違っている
- ページが長くなりすぎて、対応が必要な部分が本文に埋もれる
- レビューのコメントが片づかないまま、ページだけが残る
どれも、誰かが定期的に見直していれば防げる話です。でも、その見直しに半日を確保するのって、なかなか順番が回ってこないんですよね。
この1か月で変えたのは、手入れを速くすることではなく、手入れすべき場所を探す工程のほうを手放したことでした。 どこを直せばいいかさえ分かれば、直す作業自体は10分で終わることが多いので。
というわけで今回は、実際に任せるようになった5つの場面を、順番に見ていきます。使っているのは、ナレッジベース管理のONES Wikiと、そこに組み込まれたAIアシスタントのONES Assistantです。
手入れが続かない理由は、作業より「特定」にあった
本題の前に、ひとつだけ下敷きを。
ドキュメントの手入れが止まるのは、直すのが面倒だからじゃありません。どのページを直せばいいのかを、人間が思い出さないといけないからです。思い出すには全体を見渡す必要があって、見渡すには時間がいる。はい、ここで止まります。
この「特定」って、条件さえ言葉にできれば機械のほうが得意な作業ですよね。ただ、条件を言葉にするとき、範囲の指定がいちばん面倒になります。
で、ONES Assistantで効いているのが、その範囲を文章で説明しなくていいところでした。入力欄の＋ボタンから、ページ、スペース、課題、今使っているフィルター条件を、そのままBoxとして指示の中に放り込めます。一覧で絞り込んだ状態を、そのまま渡せる感覚です。
あとはこちらが出力の形を決めるだけ。これから出てくる5つ、全部この骨格の上に乗っています。
その1：公開前のページを、抜けている観点で見てもらう
まずは、書き終えたページを公開する前のチェックから。
ページを開いたままONES Assistantを呼ぶと、今見ているページが自動でコンテキストに入ります。 範囲を指定し直さなくていい。そのうえで「構成と表現を整理したいので、指摘だけ返してください」と頼みます。
ここ、ひとつコツがあります。「ページ本文は書き換えないでください」を添えること。 これを入れないと、親切に直された状態で返ってきてしまうことがある。直すかどうかはこっちで決めたいので、この一文は毎回入れています。
はい、返ってきたのがこの画面です。
冒頭にちゃんと「ページ本文は書き換えていません。以下、指摘のみです」と断りが入っていますね。中身は3本立てで、1つ目が見出しと構成の話。冒頭の作業メモが要件本体と混ざっている、章ごとに扱っているものの種類が揃っていない、補足の書き方が場所によってバラバラ。
なるほどなるほど。言われてみれば全部そのとおりです。
ただ、実際にいちばん効いたのは、ここじゃなかったんです。3つ目の「書き漏れていそうな観点」のほう。
設定のデフォルト値。保存に失敗したときの挙動。権限は個人設定なのか管理者の一括設定なのか。通知の許可を取るタイミング。タイムゾーンが変わったときの扱い。
……これ、全部書いてないです。しかも、書いてないことに自分では一生気づけないやつです。書いた本人には自明すぎるので。
第三者の目を公開前に毎回はさめるようになったのが、この1か月でいちばん大きかったかもしれません。
その2：長くなったページから、やることだけ引っこ抜く
これは軽い話です。
運用手順や設計メモのページって、追記を重ねるうちにどんどん長くなりますよね。長いこと自体は別に悪くないんですが、「で、結局いま誰が何をすればいいの?」が本文に溶けてしまう。
なので、今のページから対応が必要な項目を全部抜き出してもらいます。返ってきた一覧を見て、まだ生きているものだけページの先頭に残し、終わったものは記録として下に送る。それだけ。
長いページを読み直す工程が、一覧をざっと確認する工程に置き換わった形です。
その3：コメント欄に置きっぱなしの決定を、本文に引き上げる
レビューが活発なページほど、コメントが溜まります。議論としては健全なんですが、時間が経つと「このコメント、結論出たんだっけ?」が分からなくなる。
ここも、今のページのコメントをまとめてもらいます。議論の要点と、対応が必要なまま残っている項目が整理されて返ってくるので、決まったことを本文に反映して、コメントを閉じる。
コメント欄にしか書いていない決定事項って、次に読む人にとっては存在しないのと同じなんです。だからここは意識的に回すようにしています。
その4：同じことが2か所に書かれていないか、スペースごと探す
さて、ここから単一ページを離れます。
重複と食い違いって、探しにいかないと見つかりません。しかも見つかるのはたいてい、誰かが古いほうを読んで間違えたあとです。悔しい。
そこでスペースをBoxで放り込んで、「このテーマについて書かれているページを全部挙げて、食い違いがあれば両方並べて」と頼みます。ONES Assistantのナレッジベース検索は言い換えや近い表現も拾ってくれるので、見出しの言葉が揃っていないページも引っかかります。
まず返ってくるのが、該当ページの一覧。
……お。一覧の最後の2行、見てください。
ページに添付されていたExcelの、中の行まで拾っています。 工程表の該当タスク行を根拠として挙げてきました。ドキュメントって本文だけじゃないので、ここまで見てくれるのは正直ありがたかったです。そこまで見るのか、と。
で、本題の食い違いのほうは、項目ごとに記述Aと記述Bという形で並びます。
たとえば「リトライの上限は3回」と書いてあるページと、「プッシュとメールを合わせて最大8回」と書いてあるページ。どっちも間違いではなくて、数え方が違うだけかもしれない。こういうの、人間が見ないと決められませんよね。
さらに面白かったのが、同じ1ページの中で前後が食い違っている箇所まで拾ってきたこと。ある仕様ページの第4節と第5節で、同じエラーの扱いが別々に書かれていたんです。別のページ同士だけじゃなく、1枚の中で矛盾していることもある、と。これは盲点でした。
そして最後の補足。「どちらの記述が正しいかの判定は行っていません」。
はい、これでいいんです。どちらが正しいかをAIに決めさせない。 並べるところまでを任せて、どちらを残すかは人間が決める。この線引きさえしておけば、返ってきたものを鵜呑みにせずに済みます。
その5：課題の一覧とドキュメントを、まとめて突き合わせる
5つ目。この1か月でいちばん変わったのがここです。
仕様って、課題のほうが先に動くんですよね。でもドキュメントは、誰かが思い出したときにしか更新されない。この時差が、その1からその4までの問題をまとめて生んでいる元でした。
なので、課題一覧を絞り込んだ状態のフィルター条件と、ドキュメントが置いてあるスペースを、1つの指示に一緒に入れます。
この画面、ちょっと注目してほしくて。範囲をどこにも文章で書いていません。 「どのプロジェクトの、どのステータスの課題か」を打ち込むかわりに、今見ている一覧の絞り込みをそのままBoxで渡している。そしてその隣に、ドキュメント側のスペースのBoxが並んでいる。
この2つが同じ入力欄に収まる、というのが今日いちばん言いたいことです。
左に課題の一覧が出たまま、右のパネルでドキュメント側の話が返ってきています。切り替え、どこにも挟まっていません。
で、結果の全体がこちら。
いきなり「タスク31件とスペースのページ33件を突き合わせました」と規模から入ってくるのが良いですね。結論は、日程はおおむね一致していて、ズレが集中しているのは優先度と担当者の2点。それから、ページが参照している作業番号のうち、課題側に存在しないものが多数あると。
更新候補の表は、ページ名・該当しそうな見出し・対応する課題名・理由の4列。理由の欄がかなり具体的で、「ページは最高・高と書いているが、対応する課題の優先度はすべて中」「この番号に対応する課題が存在しない」くらいの粒度で並びます。
ここまで出ていれば、あとは開いて直すだけ。判断に迷うものは「要確認」として別の表に分けられていて、更新後の文面そのものは書かれていません。 頼んだとおりに、ちゃんと止まってくれました。
そのまま投げられる頼み方、置いておきます
その5は範囲の指定が要るので、コピーして使える形にしておきますね。角括弧のところは、＋ボタンから入れたBoxに置き換えてください。
[🔍 現在のフィルター] と [📄 対象のスペース] のページを突き合わせてください。
- 課題の内容から、記述の更新が必要になりそうなページを挙げてください
- ページごとに、該当しそうな見出しと、そう判断した理由を添えてください
- 対応する課題名も一緒に並べてください
- 新しく書き起こす必要がありそうなものは、別枠にしてください
判断に迷うものは「要確認」として分けてください。推測で更新内容を書かないでください。
最後の2行、入れておくのをおすすめします。更新案まで書かれてしまうと、それが合っているかを検証する手間が増えて、結局こっちの作業が減らないので。候補と理由までで止めてもらうのがちょうどいいバランスでした。
頼み方の差は、だいたいこの形に出ます。
❌「ドキュメントで古くなってるところある?」
✅「このフィルターの課題と、このスペースのページを突き合わせて。該当する見出しと理由も添えて」
左が通らないのは、AIの能力というより、こちらが範囲と出力の形を決めていないからでした。
並べてみると、変わっているのは2列だけ
| 場面 | 渡すもの | 出してもらう形 |
|---|---|---|
| 公開前のチェック | 今開いているページ | 構成・粒度・書き漏れの指摘 |
| 長いページの整理 | 今のページ | 対応が必要な項目の一覧 |
| コメントの片づけ | 今のページ | 議論の要点と未決の項目 |
| 重複と食い違い | スペース | 該当ページと、記述Aと記述Bの並列 |
| 課題との突き合わせ | フィルター＋スペース | 更新候補のページと理由 |
骨格はどれも同じです。範囲をBoxで渡して、出力の形を指定して、判断は人間が持つ。覚えることはこれだけなので、チームに広げるときの説明もすごく楽でした。
手入れの日に、何が変わったか
以前は、月末にまとまった時間を取ってドキュメントを見直す運用でした。取れた月と取れなかった月があって、取れなかったぶんは翌月に持ち越し。そして持ち越したものは、たいてい戻ってきません。
今は、スプリントが終わるたびにその5を回して、出てきた候補を見ながらその1からその4を必要なぶんだけ。
時間は正確に測れていないので体感ですが、変わったのは総量より頻度でした。一度に見直す量が小さくなったぶん、後回しにする理由がなくなった、という感じが近いです。
自分のナレッジベースでこの突き合わせがどう返ってくるか見てみたい方はこちら → ONES.com
この記事に出てきたONES.comの製品を、ここで簡単に補足しておきます。
- ONES Wiki：仕様書や運用手順、設計メモなどのドキュメントを書いて貯めておける、ナレッジベース管理のツールです。
- ONES Project：課題やスプリントを管理する、プロジェクト管理のツールです。
- ONES Assistant：ONESの画面に組み込まれたAIアシスタントです。今開いているページやプロジェクトの内容を読み取って、質問に答えたり、文書を作って保存したりしてくれます。
回し続けるためにやっていること
洗い出した更新候補、その場で全部は直しません。直しきれなかったものは、ONES Wikiのページに一覧として残しています。日付と、出てきた候補と、対応したかどうか。それだけの簡単なものです。
残しておくと、次に回したときに「あれ、前回も同じページ出てきてるな」が分かるんです。何度も顔を出すページは、部分的に直すより構成から作り直したほうが早い。この判断材料は、記録がないと手に入りません。
あと、権限の範囲でしか結果が返らない点も、チームに説明するときに必ず添えています。自分に見えていないスペースのページは候補にも出てこないので、棚卸しの対象を広げたいなら、範囲が見えている人が回す必要があります。
おわりに
ドキュメントの手入れが続かないのは、面倒だからというより、どこを直すかを思い出す工程が重いからでした。そこをONES Assistantに任せて、直す判断だけを手元に残す。やっているのは、その組み替えだけです。
5つの場面、どれも「範囲を渡して、形を決めて、判断はこちらが持つ」という同じ形をしていました。この型さえ持っておけば、あとは自分のチームに合わせて場面を足していけます。
あなたのナレッジベースには、最後に更新されたのがいつか思い出せないページ、何枚ありますか。まずは1つのスペースを選んで、その4の重複探しから始めるのが軽いと思います。
自社のドキュメント量や権限構成でどう組み立てるか相談したい場合は、support@ones.com までお気軽にどうぞ。