「どの冊子を読むか」を人の記憶から出す12冊のマニュアルを検索できるひとつのサイトにした
ツールと機器構成がほぼ固まったところで、3箇所に散っていたマニュアルをひとつのリポジトリへ集め、検索と逆引きができるサイトにした。素の原稿だと思っていたファイルが実は生成物だったり、集約先が実はどのGitリポジトリにも属していなかったりと、動かす前に気づけてよかった落とし穴がいくつもあった。
マニュアルは、書いた人の記憶の中にしか無い索引を持っている。それを外に出す話。
NGW を動かすためのアプリは、ここまでの分割でとうとう11個になった。保守コンソール、Mac設定、構築ナビ、復旧、配布……。それぞれの使い方を書いたマニュアルも、当然その数だけ増えていく。
ところが、そのマニュアルたちの置き場所を数えてみたら、3箇所に散っていた。ある冊子は「保守コンソール」のリポジトリの中、ある冊子はその中の別フォルダ、ある冊子は全く別の場所。しかも同じ内容が2つのファイルに重複していることさえあった。
ツールと機器構成がほぼ固まった今のタイミングで、これを1箇所に集めることにした。
「正本」だと思っていたファイルが、実は生成物だった
最初の作業は単純なはずだった。マニュアルのファイルを集めて、日本語のファイル名に変えて、1箇所に置く。それだけ。
ところが調べてみると、11冊のうち8冊は「Marp用のスライド原稿」という体裁のファイルで、一見するとそれが本体に見える。だが実際に手で編集されているのは、もう一段階手前にある「素のMarkdown」で、スライド版はビルドスクリプトが毎回そこから作り直す生成物だった（この「Markdownで書いてMarpで冊子にする」流れ自体は、以前の記事に書いたとおりだ）。ファイル名だけでは、どちらが正本か分からない。
このズレに気づかずに「見た目が原稿っぽいファイル」だけを集めていたら、次にビルドスクリプトを動かした瞬間、集めたはずの手直しがまるごと上書きされて消えていたはずだ。移動する前に、どのファイルが本当の入力で、どのファイルが出力なのかを1冊ずつ突き合わせる作業が要った。
集約先が、実はどのリポジトリにも属していなかった
もう1つ、動かす前に気づけて良かったことがある。
集約先として決めていたフォルダは、以前から「特定の団体向けの構築手順書」を置くための場所として存在していた。てっきりどこかのGitリポジトリの中だと思い込んでいたが、確認してみるとどのリポジトリにも属さない、まっさらな未追跡のフォルダだった。17MBのPDFを含めて、何の版管理も掛かっていない。
もしこれに気づかずに、他のリポジトリで版管理されていた11冊をそのままそこへ移していたら、移動元の履歴を消しただけで、移動先には何の履歴も残らない状態になっていた。今回は集約先を新しいリポジトリとして仕立て直してから移動したので、事なきを得た。
Mac本体とVMを、後ろに付けて区別する
ツールと機器構成が固まったのに合わせて、機器の呼び方も決め直した。同じIPアドレスにMac本体とその中のVMが同居する構成なので、呼び方があいまいだと、どちらを指しているか分からなくなる。これまでも何度か、これが原因で長い時間を溶かしてきた（無人運用の記事で呼び方を5語に固定したのも、その1つだ）。
今回、管理端末は「管理端末（MacStudio）」、既存の2台は「メイン開発機」「クローン開発機」、これから組む実機ペアは「NGWLinuxメイン」「NGWLinuxクローン」と決めた。Mac本体とVMの区別が要る場面では、「メイン開発機のMac本体」「メイン開発機のNGWLinux」のように後ろに付けて書く。前に付けるより、文中で機体名を先に確定させてから中身を絞り込む順番の方が、読み違いにくいという判断だ。
12冊すべてにこの呼び方を反映させたが、1つだけ手を付けなかった場所がある。アプリの画面に実際に表示される文字列だ。ダッシュボードのボタンやタブは、コードを直さない限り今までどおり「NGWメイン」「NGWクローン」と表示される。マニュアルの地の文だけ呼び方を変えて、画面の表示を引用する箇所はそのまま画面どおりに書く——という線引きにした。
検索は、賢くしないことに決めた
サイトには検索機能を付けたが、日本語の全文検索でよく使われる2-gram索引は採らなかった。実際に作って重さを測ってみたら、全文19万字・567節という今回の規模では、索引を足しても460KBほど増えるだけで、絞り込みが速くなるのはせいぜい数ミリ秒。それなら、素直に全文字列を総当たりで探す方が、実装も判定も単純になる。
賢い仕組みを先に選ぶのではなく、まず単純な方法を実測してから「それで足りるか」を判断する——というのは、今回に限らずこのプロジェクトでずっとやってきたことだ。
症状だけでは、答えを出さない
もう1つ、設計で悩んだのが「逆引き」だった。マニュアルの中には、すでに「症状→対処」の表がいくつも書かれている。これを1箇所に集めて検索できるようにすれば、トラブルのときに助かるはずだ。
ところが集めてみると、同じ症状（例えば「画面が真っ白」）が複数の冊子に登場し、しかも冊子によって対処がまるで違うことが分かった。新規構築のときの「画面が真っ白」と、障害復旧のときの「画面が真っ白」は、原因も直し方も別物だ。
症状の文字列だけで答えを出すと、間違った対処を自信満々に見せてしまう。そこで、症状が複数の冊子にまたがっている場合は、対処を出す前に「いまどの場面ですか」と場面を選ばせるようにした。急いでいるときほど、遠回りに見える一呼吸が要る。
それでもやり残したことがある
作業の最後に、生成したPDFを実際に開いて確認したところ、何ページかで本文が下端をはみ出しているのを見つけた。慌てて直しかけたが、変更前の原稿でも同じページで同じようにはみ出していることが、Gitの履歴を遡って分かった。今回の集約作業が原因ではなく、もっと前からあった不具合だ。
今回の目的はマニュアルの置き場所を1つにすることであって、個々の原稿の作り込みまで手を広げると収拾がつかなくなる。見つけたことは記録に残し、直すのは別の機会にした。
AIとの協働作業での学び
「検証していません」という報告を、そのまま信じない。 サイトを組み立てたAIは「PDFの見た目までは確認していない」と正直に書いてきた。そこで自分でPDFを開いて確かめたところ、実際にはみ出しているページが見つかった。ただし、これが今回の変更のせいなのか、前からあったのかは、AIの報告だけでは分からない。Gitの履歴から変更前の原稿を取り出して同じ検査を掛け、初めて「前からあった」と判定できた。確認していない箇所は、報告を鵜呑みにせず自分の手で追うという当たり前の姿勢が、思わぬ手戻りを防いだ。
大きな機械的作業は、複数のAIに同時にやらせる方が速いし、質も揃う。 12冊の用語統一は、1つずつ順番にやらせるには量が多すぎた。3つに分けて並行で走らせ、それぞれに「迷ったら判断を書いて報告せよ」と指示したところ、実際にいくつもの境界事例（画面の表示を引用しているのか、単なる説明文なのか）が報告に上がってきた。それを自分の目で数か所抜き取って確認し、方針とズレている所だけ直す——という分担で、全体を見ずに1冊ずつ潰すより早く、かつ一貫性も保てた。
移動する前に「本当にこれが正本か」「ここは版管理下にあるか」を疑う癖は、人が持ち込むしかない。 生成物を正本と取り違えたり、未追跡のフォルダへ大事なファイルを流し込んだりする事故は、個々の作業が正しくても起きる。AIは頼めば正確に調べてくれるが、「何を疑うべきか」という着眼点そのものは、こちらから渡さないと出てこない。着手前に一呼吸置いて計画を確認させたのが、今回いちばん効いた一手だったと思う。