表題の通り、かつ今更感パネエなのですが、その理由を書きます。
この記事で伝えたいことを一行で
プログラムの仕様はReadmeに書いてソースと一緒に管理したら良いこといっぱいあるよってこと
予備知識
Readmeの書き方やREADME駆動開発については、他の方が書いていただいた、以下の記事がとても参考になると思います。
わかりやすい README 駆動開発
reStructedTextの記法については、以下のドキュメントが大変、参考になります。
reStructuredText入門
Markdownの記法については、以下の記事が大変、参考になります。
Markdown記法 チートシート
質問
ところで、Readme書いてますか？
reStructedText形式やMarkdown形式などで書ける以下のようなやつです。
ドキュメント更新はずっと課題
ドキュメントというものの保守コストは非常に高いんですよね。
実体験上、開発優先のプロジェクトとかですと、ドキュメント更新は後回しにされがちで、ドキュメントが最新の状態に保守されてるケースって稀です。
昔の人は言いました。「ソース嫁」と。
BTSはBTSとして使おうよ
最近のBTSのトレンドはよく知らないので誤解があるかもしれませんが、個人的にRedmineはBTSとしては優れていると思うのですよね。ただ、ドキュメント管理として使うには少し残念な印象。
プログラマは忙しいんじゃ
プログラマがやることって結構色々あるんですよね。
ソースを書いて、テストを書いて、ビルドして、テストして、コミットして、プッシュして、レビューして、マージして、リリースして。
やることが多いので、そこにRedmineの該当ドキュメントを探して（場合によってはファイルサーバから探して）更新とか入ってくると、やること多すぎで、だんだん病んでくるので、ソースの仕様はソースと一緒にReadmeを更新して、一緒にコミット、レビュー、マージした方が直感的だし、楽なんですよね。
いい感じの開発フロー
ソース修正手順として、以下のような感じになります。
修正プロジェクトをclone
修正用にブランチ作成＆チェックアウト
Readme修正
テスト修正
ソース修正&Commit
Push
Pull requestと共に、CI回す
Readmeの内容とソースの修正箇所が一致しているかとCIの結果からレビューする
マージ＆デプロイ
これだけの作業が見るとこ2箇所(リポジトリサービスとソース)で済むんですよ？
これって、とてもcoolじゃないですか？
他にもこんなメリット
また、メリットとして、ドキュメントの影響範囲を限定的にできるってのも魅力的と考えてます。
Redmineなどでプロジェクトやプログラムのドキュメントを網羅的に書くと、まぁ大体カオス化してきて、結局、階層構造でドキュメント書き始めるわけですが、そもそもReadmeなら、ディレクトリごとに書けるので、そのディレクトリ内の説明だけに限定して書けるわけですよ。
そうすると、自然と疎結合を意識してモジュールなんかも書き始めるわけですね。
これって素晴らしい。
実際に動くファイルや設定ファイルと同じ場所で管理できる上にバージョニングまでされちゃうし、ドキュメントレビューもリポジトリサービス上でできちゃう。
まとめ
そのプログラムの説明はプログラム自体と一緒に管理したら見通しも良いし、保守も楽だからやったら良いんじゃないだろうかってお話でした。