当たり前の手順も書くべし

言わずもがなだけど、あえて言語化しておくシリーズです。

このような手順を書くのは冗長だと思ったことはありませんか？

# パッケージのコンパイル

以下のコマンドを実行してデプロイしてください

> mvn deploy

（※mvnはMavenというJava用プロジェクト管理ツールのコマンドです。他言語の人は適当に読み替えてください）

もちろん、本番作業手順書などの厳格な文書なら当然書くでしょう。でも、GitレポジトリのREADMEのような内輪のドキュメントでは・・・:

• どのアプリでも Maven を使っていれば mvn deploy でコンパイルするに決まっている
• Maven を使っていることはファイル構成から一目瞭然
• うちのチームに mvn deploy を知らないプログラマーはいない（知らねえ奴はモグリだ！）

だから、あえて mvn deploy 以外の方法を取る場合のみREADMEに書いた方が経済的だと思ったことはありませんか？私はあります。

でも、やっぱり、当たり前の手順であっても、READMEに明示した方がいいと思います。理由は二つあります。

一つ目の理由は「本当にあえて省略したのか」が、読み手には分からないことです。実は重要な手順があるのにリリースを急いでいてうっかり書き忘れてしまったと誤解されるかも知れません。

もう一つの理由は現在の常識が、将来も常識である保証がないことです。実際、今は新しいツールが普及しており、mvn経験が無い Java プログラマーも多いでしょう。

もちろん、読み手が優秀なプログラマーならば「きっとmvn deployでデプロイするんだろうな」と推測はしてくれるでしょう。しかし、確信を持つには至りません。「多分そうだろうけど万が一・・・」という疑念を払うために、3分、5分、ことによると１時間費やすかも知れません。

一方で、READMEに「mvn deployでデプロイしてください」と書くのは10秒ぐらいしかかかりません。

自分の現在の10秒を節約するよりは、他人の未来の１時間を節約する方が、合理的と言えるでしょう。