鈴木うどんの横須賀おもしろ生活

撮った写真や思ったことや技術ネタなど。出来るだけ大きなディスプレイで見ると良いと思う。ここでの発言は個人の見解であり、所属する組織の公式見解ではありません。

内製サーバソフトウェアのドキュメントについて

実行方法が分かっていれば非常に簡単な内製サーバソフトウェアの利用方法を知りたいが, その案件に関わっている人がその場に居ないから実行すら不可能,そういう事象がしばしば発生する. ドキュメントを書かないことが問題だとなりがちだが, 実はドキュメントを作る運用を徹底してもなかなかうまく行かない. その原因のひとつとして,適切な場所に適切な方式でドキュメントが保管されていない,ということがあると感じている.

その背景はおおよそこんなところだろう. ドキュメントは多くの場合マイクロソフト製のツール(どういうわけかエクセルが多用される)で作成される. そして,Windowsで運用されるファイルサーバ上の連番で管理された深い階層のディレクトリのどこかに丁寧に保管される.これはそれなりに正しいように思える. しかし,そのやり方はサーバソフトウェアの起動方法や利用方法を示したドキュメントに限っては全く正しくない. そのドキュメントがどこに保管されているか発見することが困難だからだ. マイクロソフト製のツールで作成されたドキュメントはどういう訳か全文検索が困難だ. そういう状況でどうやって膨大な量のファイルが詰まったファイルサーバから適切な ドキュメントを探しだせようか. 優れた技術者は find や grep といったコマンドを駆使してドキュメントやコードを読むはずなのに.

では,サーバの実行方法を記すにはどうするべきか, そのサーバ自体にテキストファイルでドキュメントを設置するのが正しいと考えられる. 例えば,ログインしたら motd でドキュメントの位置を示せば, ユーザはまずどのドキュメントを読ぶべきか分かるのでとても良い. また,ホームディレクトリに README を設置するのもなかなか良い方法だと思う. そして man が書いてあればなお良い.