満足せる豚。眠たげなポチ。

Google Doctype is an open encyclopedia and reference library. Written by web developers, for web developers. It includes articles on web security, JavaScript DOM manipulation, CSS tips and tricks, and more. The reference section includes a growing library of test cases for checking cross-browser and cross-platform compatibility.

Google Doctype is 100% open.

Open source

Open content

Open to contributions from anyone

ざっと眺めてみたところ、まだ内容はこれから詳しくしていくという様子だけれど、それでも網羅的な情報が整理された状態で閲覧できるようになるかもしれない点や Web Security が HOWTO のトップに来ている点など見ると、今後の展開に期待してしまう。

また、overview のページに "As the open web evolves, we would like to keep articles section of Google Doctype as up-to-date as possible, for as long as possible. This requires collaborative editing." と書かれているとおり、（既存の Web の情報とは違って）できるかぎり最新の情報で更新し続けていくということなので、これが実現すると Web アプリの開発入門者は「とりあえず Google DocType を見とけ」という風になるのかもしれない。overview の "Why create Yet Another Web Reference?" の項は他の内容も Google DocType の存在意義を確認する意味で必見。

ちょうどこれを書いている合間にもちょくちょくサイトの様子が変わっているので、まさに目下進行中な様子でおもしろい。

permalink

業務システム開発でドキュメントを作ることについて

by tanabe on May 15, 2008

職場でここ３～４ヶ月の間、システム再構成のためのドキュメント化プロジェクトというのを進めてきた。その中で『ドキュメントを書く』ということに対する意識が随分自分の中で変化したので、メモしておく。

まずは経緯から。

そのシステムは、いわゆるレガシーなシステムで、十数年来の歴史を持つ。これまで基盤が多少変わることがあっても基本的にソフトウェアアーキテクチャ（どのような単位で機能をモジュール化するか、どのように機能を抽象化し変化に対して柔軟にするか）に変わりはなく、作った当初の設計にツギハギしてメンテナンスを続けていた。

元々は、一体何をすれば増員以外の手段で開発量を上げられるかということを議論していた。現行のアーキテクチャのままでは求められる開発期間とバージョンアップのサイクルに対して近い将来限界を迎えることが明白であったためだ。

今のアーキテクチャや設計に問題があり、メンテナンス性を大いに損ねているという点では全員の意見が一致していたが、はたしてそれをどうするべきかという話になると、「そうは言っても、全体の仕様がわからない」「正解となる姿がアプリケーション自身しかないので困る」といった意見が出て先へ進まない。

そこで、それならその全体仕様がわかるドキュメントを作ろう、ということでドキュメント化プロジェクトが始まった。

次にプロジェクト開始時点でのぼくのドキュメントに対する考え方。

けっきょくへたくそな設計書こそが諸悪の根源なんだよ。仕様を失いそうなら、失わないようなコードを書く。仕様書としてまとめて管理したいようなものはコードをまとめる。だって、それこそがメンテのネックとなるようなルールやデータなんだから。

プログラマが自分のためにやっている実践的な工夫（内部用のメモ・ドキュメント）っていうのは、まさにもっとも貴重なノウハウの塊みたいなものなんだから、それこそがコードやデータ、データ構造で表現されている必要があるんだよ。

あとは適切な名前をつけることに注力したり、コメントでサポートしたりしていくべきなんじゃない？

というようなとにかく大事なものはプログラムで表現してしまえ、というものだった。

そして、約90日間ほどコードを書く人や書かない人や書けるけど不得意な人とほぼ毎日一時間の議論をした結果、今ドキュメントについて理解していること。

ドキュメントを作る目的は、書くことでも読むことでもない。レビューすることを通じて、互いの理解の差を埋めることが目的である。
ドキュメントに必要な内容はチームの成熟度、メンバーのスキルによって異なる。
ドキュメントを作るというのはプロジェクトの文化を作ることの一面であり、ドキュメント作成というツールを使って、文化やスキルレベルの違う後続のチームメンバーをトレーニングしていく活動である。（その意味ではスキルが上位の人もトレーニングの対象となる。）

だから、この視点から考えると、

コードがドキュメントかどうかは関係ない。「コードがドキュメント」というときのコードはドキュメントの一つの形といえる。（たまたまコンパイルも可能であり、情報が DRY に管理できるというメリットを持っている）だから、コードがドキュメントと言える環境が整えば、それは真になるし、整わなければそれは単に独りよがりなドキュメント不足のプロジェクトだ。
ドキュメントを作るとは、標準化することではない。マニュアル化することでもない。
ドキュメントを書くことと人に説明すること、フィードバックを受けることはワンセット。

この考えに立ったときの難点は、「ドキュメントとはこうあるべきだ！」という絶対的な指標を示せない点。その代わりに薦める考え方は「まずは何か書いてみて、隣りの人に説明をして意見を聞いてみたら？」というもの。レビューを通じて受けたフィードバックは、「ドキュメントに盛り込む内容のスコープ（広さと深さ）」と「ドキュメント自体の内容」、さらに「システム開発に対する考え方」を常に更新し共有していく。

書いていると当たり前すぎる内容だし、もちろんこれだけで良いドキュメントが書けるかというとまったくそんなことはないのだけど、考え方の基本として自分の中で大きな転換だったのでメモしておく。

業務システムの開発の中で、ドキュメントほど一般的な問題でありながら適切な解が出ていないものはないと思うのだけど、他の人たちはどんな風に考えながら、どういうドキュメントを書いているのかなぁ。（SOX だとか、プライムからの強制フォーマットだとか、いろいろな視点があるとは思うけどさ。）

permalink

このページの上へ▲