十分に仕様が定まっていない開発をすると、無効になったドキュメントが残りやすい。
仕様書をネットワークドライブやSVNなどで共有していても、ドキュメントの管理は十分じゃないことを感じる。
ある時点ではそのとおりであったドキュメントが、開発のための仕様を変更していくと、実装とドキュメントの乖離を生じていく。
#ifdef #endifやブロックコメント化をしていって、従来あった機能がなくなっていくことがある。
だからといって、元々のドキュメントにその改変が改変されずに残りがちです。
ソースコードはバージョン管理
ソースコードへの変更はバージョン管理されているので、だめだったら戻すことが容易です。そのため簡単に動作の確認をしますが、十分にその改変が安定していて使い物になることを確かめきる前に、ドキュメントを変えることは控えがちになります。
そのうち、別の項目についての改変をすることになって、その前の変更についてドキュメントを変えることが忘れ去られてしまいがちになります。元のドキュメントを書いた人でない場合には、ソースコードの改変に対応して改変しなければならないドキュメントがあることなど気がつかない場合もあります。そのことも、ドキュメントが実装のコードの乖離を生じやすい要因となります。
ヘッダファイルによる仕様の管理
この問題に対する私の提案は、仕様に関する記述は極力ヘッダファイルによる記述に移行することです。
ヘッダファイルのドキュメンテーションコメントの場合には、ソースコードと別ファイルのドキュメントよりは、メンテナンスされやすくなります。（それでもドキュメンテーションコメントが古くなってしまう場合もある）
詳しくは、以下のリンクに既に書いた内容をご参考ください。
ヘッダファイルという名の仕様書
追記
MarkDown ファイルによるドキュメントの作成
Github で公開されているソフトウェアのReadmeやInstallの手順は .md という拡張子のついたテキストファイル(markdown ファイル)で書かれているのが大半だ。
それをまねて、自分の作るライブラリもmark downファイルでドキュメントを書くようになった。
こうすることで、ソースコードと同様にバージョン管理することが楽になった。
いつドキュメントがどのように改版されたかの違いがmark downファイルだと見やすい。
全てがすべてmark down ファイルで十分とは思わない。mark down ファイルで十分な分野があると主張しています。
Jupyter notebook で実行結果のドキュメントを作る
Jupyter notebook を使うと、スクリプトとスクリプトの実行結果、markdown 記法のドキュメントとをipynb のファイルに書き込むことができる。実行可能なドキュメントなので、計算条件が変わったときには、スクリプト部分を修正して、全てのcellを再実行させることで、ドキュメントを最新の状況に更新できる。
そのため、ドキュメントが古くなることを大幅に減らせます。