数年前に書いた社内ライブラリの文書が今でも改訂され参照されている、という経験をもとに社内用文書や教育のあり方について語ったブログ記事です。

書籍『Building Application Frameworks』（⁠John Wiley & Sons Inc）では、フレームワークの文書を「サンプル」「⁠レシピとクックブック」「⁠契約」「⁠デザインパターン」「⁠概要」「⁠リファレンス」「⁠設計ノート」に分類しているようで、ブログ筆者はその中で最も欲しいものはサンプルである、という結論に達したようです。また、過去に作られたアプリケーションからコピー&ペーストされることが多く、質の悪いコードのまま利用されることがあるという事実により、正しいコピペ素材を提供するためライブラリの最頻イディオムをサンプルつきクックブックとしてまとめることが最善である、と考えたようです。ほかにも、

• リファレンスを書くのに多くの労力が要するが、大半の文書は読まれない
• コードはビルドできる範囲の最小構成にし、xUnitも組み込まない
• 文書に練習問題をつけても、自習なんてしない
• 問題に締め切り期限を設けて、レビューを行うと効果がある

など、実際の経験に基づいた考察が挙げられており、説得力があります。

URL：http://dodgson.org/omo/t/?date=20070706#p02