こんにちは。フィックスポイントの冨です。

最近、普段あまり触らないようなシステムを、ドキュメント記載の手順にしたがって 操作する機会が何回かあったのですが、想定通りに完了しない。
おかしいなあとスクリプトや設定ファイルの中身を読み始めるのですが、 明らかにドキュメントに記載されていない設定項目があったり、 スクリプトを動かす前に必須の設定事項があったりと、いろいろと驚かされたわけです。

直近の担当者に問い合わせてみると「それは記載漏れでしたね。」という場合ともかく、 「ああ、そこ、みんなハマるんですよね。」となると、おいおい！となります。
分かっているなら更新しておいてくれよと。

ドキュメントの重要性はみんな理解されているのですが、 どのように書くか、どのようにメンテナンスしていくかについては、 意外と二の次にされている事も多いなあと感じます。
特に開発に忙しい時はどうしてもドキュメント執筆の時間の優先度は下げられてしまいますよね。

運用設計の段階で、用意すべき文書の標準の整備が行われているところも多いかと思いますが、 実際の文章を読むと、MECE=抜けもれなくダブりもなく網羅するとか、用語定義の明確化、 暗黙の了解事項が多くてハイ・コンテキストな文章になっていないかなど、 いろいろと気になる所が出てきます。

技術ドキュメント執筆については、あまり参考書は多くないのですが、 どのような文章を用意して、具体的に何を書くべきかについては、 近藤誠司さんの「運用設計の教科書」という本は参考になると思います。

文章も書き慣れていないとハードルは上がる一方ですが、 Sphinxなどの作成支援ツールなどもあるので、 ご興味ある方は研究してみると良いでしょう。

文書管理も、以前は「Excelファイルに、”案件名-YYMMDD.xlsx”って日付をつけているんだよ」と 自嘲気味に話される事も多かったですが、 最近は差分・履歴管理もできるドキュメント管理サービスやネットワークドライブも増え、 ずいぶんと楽になりました。

時間や予算の制約のある中、きちんと分かりやすく書き切るのは難しいですが、 リモートワークの拡大、メンバーの流動性向上、ライフサイクルの短期化が進む昨今では、 ドキュメントの品質は、致命的な知識のロストを生む可能性を秘めています。
将来的な業務品質を担保するためにも、ブラッシュアップを心がけていきたいものです。