「プログラマーにドキュメントを書かせるには？」

http://developers.slashdot.jp/story/12/01/17/0133243/
http://www.infoworld.com/d/application-development/how-get-developers-document-their-code-183908

「書かせる」って随分と上から目線．しょせんプログラマに信頼されない管理職のやることなんて，この程度か．*1

この問題って色んな問題をはらんでいるので，答は簡単ではない．下の例もごく一部だと思う．

ドキュメントを沢山書け

「とにかくドキュメントをたくさん書け．今上手く言ってないのはドキュメントを書かなかったせいだ．ドキュメントを書くようにすればきっと上手くいくはず．たぶん上手くいくと思う．上手く言ってくれないと困る！」みたいなの

どうやれば成功するのか理解してない無能な管理職にこういう人が多い．つまり多くの日本企業がこの失敗パターンの虜になっているということだ．*2
「プログラマに書かせろ」
「ドキュメントをきちんと管理しろ」（≒ ドキュメントの事は良く話からんので後は任せた）
「バグの原因は『せっけーこーてー』に時間をかけなかったせいだ．」（≒プログラミングのことは，以下同文 ）
「『せっけー』さえできればプログラムは完成したも同然．」（≒以下同文）

なれる!SE 4 誰でもできる？プロジェクト管理 (電撃文庫 な)

「無理です」
「え？」
「無理です世無理．こんなの全部やってたら，実際の構築作業に支障を来します．お話になりません．何を考えてるんですか御社は．」
「なにって．．．」
(中略)
「レポートやミーティング参加にも工数がかかるんです．我々も限られた予算でご発注いただく以上，こんなことで稼働を消費したくありません．ベターメディアさんだってそうじゃないんですか？」

http://d.hatena.ne.jp/JavaBlack/20110207/p1

読まれないドキュメント

「沢山書け」のバリエーション．

とにかく書けと主張はするけど必要性やコストを考えずに主張しているので，実際には誰も使わない不要なドキュメントだけが作られる．それが無駄なことは周知の事実なので誰も書きたがらない．結局貧乏くじを引いた人に押しつけられて，申し訳程度に処理される．

我が社のルールでそう決まっている

「読まれないドキュメント」のバリエーション．

「昔の人が決めたから」という理由で，不要なドキュメントを作ることを強いられる．プログラムの性質によって必要なドキュメントが千差万別なので，各ドキュメントをルールで一律に決めても，それがうまく行く事はまれ．

間違った道具を使う．

筆頭はMS-WordやExcel．さらにヒドイのになると全部プリントアウトしてファイルに保存しろとか言い出す．紙に手書きとか修正も全部紙に反映しろとか言い出すと悪夢が始まる．またワードやExcelはバージョン管理との相性が最悪なのも問題の一つ．こんなのでドキュメントを残すのは，バージョン管理ツールを使ってなかった前世紀の遺物にしてほしかった．*3

悲しいかな，これも無能な管理職にこういう人が多い．つまり多くの(以下省略)

UMLやフローチャートを書く

間違った道具を使う ＋ 時代錯誤の最凶コンボ．こういう会社では転職を考えざるを得ない．

低スキルプログラマ

スキルが低すぎて，自分の書いているプログラムを理解していない．なんでそうなるか，どのアルゴリズムを使ってどんな手順で実現されているか理解していない．APIの設計さえも丸パクリなので設計思想を理解してない．そういうプログラマにはドキュメントを書けと言っても書けるわけがない．

しかし，なんでそんな人材がプログラマとして仕事をしているのか．これも突き詰めれば，「プログラミングは誰でもできる」神話や「学歴不問・未経験者歓迎」思想に洗脳された，日本的経営の弊害といえる．

コメントがない

低スキルプログラマの別バージョン．

プログラムの品質が悪く，ドキュメントを作る前にコメントを追加させることになる．

スパゲッティプログラム

低スキルプログラマの別バージョン．そしてプログラマにとっての最大の悪夢であり，時に経営の根幹を揺るがし中小企業を倒産に追い込む技術的負債．

プログラムの品質が悪すぎて，ドキュメントがあっても役に立たない．こういう時はドキュメントを書く工数を削ってでも，コードを書き直す工数を捻出せざるを得ない．

プログラマが何をやっているか知らされてない

かならずしも無能でなくても，上の人間が無能だったり秘密主義だったりで現場には何もしらせない場合，ドキュメントに書ける内容もなくなる．

だが、縦の情報連携、つまり元請けたるエースシステムと、下請けたるわれわれの間の情報交換については、強化するどころか逆効果でしかなかった。エースシステムから降りてくる情報が、実装に必要な最低限の量に絞られてしまったのだ。

　その主な理由は、エースの上級SE高杉さんと、うちの東海林さんのひそかな対立にあった。端的に言えば、東海林さんが高杉さんの要件定義や設計の不安要素を遠慮なく指摘し、高杉さんがそれを嫌ったからだ。高杉さんがそう公言したわけではないが、そうとしか考えられなかった。

http://el.jibun.atmarkit.co.jp/pressenter/2011/08/11-bbd5.html

しばらくすると、彼が不安がりだした。
「この装置が何に使われるのか、全然教えてくれない。だから、どのくらいの信頼度を考えて仕上げれば良いか分からない」
と悩んで相談に来た。フロッピィーディスクドライブだから、コンピュータの記憶装置としては極めて一般的な装置である。その利用が何か特定の分野で使われるのか、あるいは秋葉原みたいなところで不特定多数を相手に売られるのか、それによって設計も異なってくる。頻繁に故障しても笑って済ませられるものから、万一故障が起きると生命が危なくなる場合まで様々である。

しかし、取引先は、仕事に必要な最小限度のことしか教えてくれない。これでは、開発担当者は不安である。何とかしなければということで、私が一緒に工場まで行った。

工場の入り口で登録してから、担当者の机のわきを通り、一番奥の会議室で打ち合わせを行なった。会議で適当に聞き出すつもりだったのだが、実は担当者の机のわきを通った瞬間に全て分かってしまった。設計図が机の上に広げてあり、その大部分は他の用紙で隠されていたのだが、その装置の特徴的部分がつい見えてしまったのである。だから、会議では適当に挨拶だけをして帰った。

ある種の店に置く装置で、一度の売り上げが数千円の商売の売り上げを管理する装置であった。何も隠す必要はないではないか、隠すこと自体が不思議でならなかった。

これで全てが分かり、彼も安心して仕事に励み、予定通りに納品できた。

http://karetta.jp/book-node/okite/003185

金と時間が無い

予算と納期がケチられたために，ドキュメントを書く時間がなくなった．

ブラックIT業界の十八番「サービス残業」で対応するにも限界がある．

評価制度の問題

プログラムのソースコード行数やファンクションポイント数や人月単価で評価する組織においては，ドキュメントやコメントを書けば書くほど評価が下がる．ゆえに評価を最大化するためにはそれらを書かずに，ひたすらコードだけ書く事が推奨される．*4

これは「その組織／管理職／経営者がコメントを書かないことを推奨するインセンティブを課している」という問題であって，個々のプログラマの問題ではない点に注意が必要である．

ノウハウを教えたらクビを斬られる

「評価制度の問題」のバリエーション．ドキュメント化すれば済んじゃう程度のことをドキュメント化すると，その人間は交換可能だからとクビを斬る．だから有能な人ほど自分のノウハウを秘匿することで自分の評価を高めざるを得ない．

これも「その組織／管理職／経営者がコメントを書かないことを推奨するインセンティブを課している」ということであって，個々のプログラマの問題ではない点に注意が必要である．

文書化できないノウハウまで文書化することを求める．

一例としてはプログラミングテクニック．変数名のつけかたとかメソッド分割のような初歩的なものでも学習しないと身につかないし，センスの無い人には永久に理解できない．

文書化されているノウハウまで再文書化することを求める．

たとえばGoFのデザインパターン．知らない人はそれも全部文書化することを求めるが，GoF本さえ読んでない人は文書化したってどうせ読まないし，百歩譲って仮に読んだとしてもおそらく理解できまい．

オブジェクト指向における再利用のためのデザインパターン

十年以上前に，既にGoF本のような名著に記された既知のノウハウと同じ物を，改めて苦労して文書化するのは車輪の再発明もいいところ．賽の河原の石積みのような作業で，実に虚しい．

ドキュメントを先に書いてからコードを書く

プログラミングを建築物の例えでしか理解できない無能管理職にありがち．

やり方が間違っているのでできるドキュメントの質が悪く非効率．

仕様が決まってない／仕様を誰も知らない

特許庁の基幹系刷新がたぶんこのパターン．

特許庁の人間も個々の現場のことしからしらず，全体像を把握しているものは誰もいない．しかもそれを電子化するためのノウハウとなると皆目見当がつかず，全体のあるべき姿はおろか，青写真さえも誰一人として描けない．

そんなドロドロのデスマーチは意外と多いようだ．
http://myatsumoto.hatenablog.com/entry/2012/01/27/040923
http://myatsumoto.hatenablog.com/entry/2012/01/27/040923
http://www.jpo.go.jp/cgi/link.cgi?url=/shiryou/toushin/kenkyukai/jyouhou_iinkai.htm

*1:原文は"How to get developers to document their code" らしいけど，これってもう少し弱いニュアンスなのかな．日本の管理職だと平気で「書かせる」っていうと思うけどね．

*2:えてしてこういう管理職は，コスト意識が極めて希薄．ドキュメント一行あたりのコストパフォーマンスがどれだけなのか，全く見積もりもしないままに，やれ書けそれ書け死んでも書けと言ってくる．死ぬのが自分じゃないからと気楽に言ってくれるよなあ．

*3:納品専用の「見栄えのするドキュメント」作成なら勝手にしろ．ただしそういうものの作成工数は個別に請求すべきで，プログラマの工数を無駄に消費してほしくない．

*4:同様の理由でこういう組織においては自動化も御法度である．テストもビルドも全部マニュアルで行うことが推奨される．なんてアナクロな．