この記事で分かること
開発が終わったシステムの保守・運用ドキュメントを、Markdown形式に移したときの記録です。
- どの種類の手順書をMarkdownにしたか
- 全部を移さず「8割」で止めた理由と、Excelのまま残したもの
- 始めた当時はまだAIがレビューや修正に使える段階ではなかったのに、なぜ形式を変えたのか
- 実際にAIが実用的になった今、どう効いているか
一般論としての「ドキュメントをAI Readyにしよう」という話ではなく、実際に手を動かして移し終えた側の記録です。まだ手をつけられていない領域もそのまま書いています。
どんな場面で使うか
開発が完了したシステムには、そのあと長く使われる保守・運用のドキュメントが残ります。これらは、書いた本人以外が読む前提の文書です。
自分の場合は、開発が終わったシステムについて保守と運用に関わる手順書をMarkdownにし、あわせてこれから開発するものについても同じフォーマットと内容が使えるようにする、というところまでを目的にしました。1つのシステムのための整理ではなく、次に作るものにも流用できる形を作る、という位置づけです。
同じような状況にあるのは、たとえば次のような場面だと思います。
- 開発が終わって運用フェーズに入り、手順書の置き場と形式がバラバラになっている
- これから作るシステムのドキュメントの型を決めたい
- 社内の文書をAIに読ませたい／RAGに入れたいと考えている
何をMarkdownにしたか
移したのは、保守と運用に関わる次のような手順書です。
- データベースの変更・メンテナンス
- 定期的に作業が必要な、社内特有の作業
- イレギュラーで発生するが、作業内容は決まっている運用
- デプロイ
並べてみると共通点があります。いずれも手順が確定していて、その通りに実行することが目的の文書です。誰がやっても同じ結果になるべきもの、と言い換えてもいいかもしれません。
逆に言えば、議論の余地が残っている文書や、これから決めていく文書はここには入っていません。この違いは、あとで触れる「まだ手をつけられていない領域」につながります。
全部は移していない — 8割という線引き
保守・運用に関わるドキュメントのうち、Markdownにしたのは8割です。残りはそのままにしてあります。
Excelのまま残したのは、表が多く入るものです。
「AI Readyにするなら全部を構造化テキストにすべき」という考え方もあると思いますが、実際にやってみると、表が主体の文書までMarkdownに押し込むのは割に合いませんでした。ここは無理をせず、Excelのまま残しています。
そしてもう一つ、要件定義・設計に関わるドキュメントには、まだ手をつけられていません。必要だとは思っていますが、検討できていない、というのが正直なところです。
つまり現状は次のようになっています。
| 対象 | 現状 |
|---|---|
| 保守・運用の手順書（表が主体でないもの） | Markdownに移した（全体の8割） |
| 表が多く入るドキュメント | Excelのまま残した |
| 要件定義・設計に関わるドキュメント | 未着手。必要だとは考えている |
やってみて意外だったこと
始めた当時、AIはまだ「使える」段階になかった
この取り組みを始めた当時は、AIがドキュメントのレビューや修正に使えるものではありませんでした。それでも、将来そういう用途で使えるようにという意図でファイル形式を変えました。
ただ、どれくらいAIで使えるようになるのかは、当時まったく見えていませんでした。見込みがあって動いたというより、形式を変えておけば選択肢が残る、という程度の判断です。
想定していなかった副次的な効果のほうが先に来た
AIが使えるようになるより前に、別のところで効果が出ました。
一つはGit のような差分管理が行いやすくなったことです。どこがどう変わったのかが見えるようになりました。
もう一つは、扱う側が慣れたことです。最初は VS Code などの環境を入れるところから始まり、書き方を覚える必要もあって少し煩雑でした。それが、自分も含め周りの人も次第に慣れていき、標準的に扱える形式になっていきました。当初は移行のコストだと思っていた部分が、時間が経つと前提に変わっていた、という感覚です。
現在のAIのレベルなら、ほぼ手を加えずに修正・レビューできる
そして今、当初の目的だった用途が実際に成立しています。資料と修正内容を入れれば、ほとんど手を加えずに修正やレビューが可能になりました。
さらに、Excelファイルと違ってAIが読みやすいため、RAGに入れて使いやすいものになっています。ファイル形式を変えたことが、そのまま活用のしやすさにつながった形です。
つまずいたところ
振り返って、負荷がかかったのは導入の入口でした。
- 環境を用意する必要があった — VS Code などを入れるところから始まります
- 書き方を覚える必要があった — 少し煩雑に感じる期間があります
ただ、これらはいずれも最初だけの負荷でした。慣れてしまえば標準的に扱える形式になったので、ここで止めてしまわないことが結果的に重要だったと思います。
まとめ
- 開発が終わったシステムの保守・運用手順書（DB変更・メンテナンス、定期作業、内容の決まったイレギュラー運用、デプロイ）をMarkdownに移した
- 移したのは8割。表が多く入るものはExcelのまま残した
- 始めた当時はAIがレビューや修正に使える段階ではなく、将来を見越しての形式変更だった
- 先に効いたのはGitでの差分管理と、周囲を含めて標準的に扱えるようになったこと
- 現在のAIのレベルであれば、資料と修正内容を入れればほとんど手を加えずに修正・レビューができる。RAGにも入れやすい
同じ状況の人へ
以前とは違ってAIによる支援が高度化しているので、手間ではあるものの、手順書のMarkdown化はおすすめしたいと思っています。始めた当時は効果が見えないまま進めることになりましたが、今から始める人には、少なくとも「何のためにやるのか」がはっきりしている分やりやすいはずです。
自分自身もまだできていませんが、要件定義や設計に関わるドキュメントの構造化も今後検討したいと考えています。
