ドキュメントの形式、何使ってますか?

設計書なり、マニュアルなり、正式に納品するドキュメントを記述するフォーマットの王者は言うまでもなくMS-WORDだと思います。今日は、でもホントにMS-WORDがベストの選択肢なのか?ということについて考えてみたいと思います。

文書を作成するということに関してMS-WORDほど多機能で使いやすい製品は他にないでしょう。
しかし、MS-WORDが得意なのはあくまでも紙に印刷することを目的にした文書の作成です。
WORDで書かれた文書をディスプレイ上で読むのは、意外にしんどい作業です。文書のサイズが
大きければ大きい程つらくなってきます。
同じ内容でMS-WORDとHTMLの2つの形式でドキュメントが提供されている時、人はどちらを選択するで
しょうか?僕なら迷わずHTMLを選択しますね。同じ選択をする人は多いのではないかと思います。

後で手軽に閲覧することを考えたらHTMLの方が使い勝手が良いにも関わらず、MS-WORDが選ばれる理由の一つには、人間には作成したドキュメントを紙出ししたいという根源的な欲求があるということが挙げられる思います。
せっかく作成したドキュメントですから、きれいに印刷して、分厚いキングファイルに閉じて、背表紙をつけて、机の上に並べて、「ああ仕事したなぁ、オレ」という満足感に浸りたい。それは人の情というものでしょう。しかし、その満足感はあくまでも自己満足に過ぎないことに注意が必要です。そのように作成された文書の多くは２度と人の目に触れることなく死蔵されていくことになるのです。それはもはや文書のための文書であり、人と人とのコミュニケーションを助けるという本来の目的を果たしていません。文書はもっと「読まれること」を意識して作成される必要があります。

そうは言ってもいきなりHTMLで文書を書く事には無理があります。HTMLにはWORDと裏腹に「書きづらい」という欠点があるからです。
なので、文書を書く直接のフォーマットとしてはWikiライクな形式を採用するのが良いのではないかと思っています。Wiki形式を一旦XMLに落として、そこからXSLTでHTMLに変換すれば、XMLからPDFやRTFなど他の形式に変換することが出来てよさそうな気がします。

そこで先日ちょっと紹介したAPTが登場します。APTはWikiライクなフォーマットのテキストファイルをDocBook XML形式に変換できるので、そこからは努力次第でどうにでも好きな形式に変換できます。
変換にCocoonなどを使うとさらにスマートでかっこよくなるのではないでしょうか。

ブックレビュー番外編：女帝

書名：女帝
画：和気一作
作：倉科　遼

今日は気分を変えて漫画喫茶で書いています。ブックレビューも初の漫画です。今よんだ「女帝」という漫画が面白かったので、紹介したいと思います。全部で20巻以上あるので全部はよんでませんが。
話は母に先立たれた女子高生が水商売の世界で生きていこうと決意し、"女帝"として駆け上がっていく様を描いたものです。これだけ書くとえらい下世話な話を想像する方も多いと思います。実際、性的な描写もばんばん出てくるので、お子様にはお勧めしませんが、最近読んだ漫画の中でも相当面白い部類にはいると思います。
とくに引き込まれるのは水商売で身を立てようとする女性たちの仕事へのビジョンとモチベーションの高さです。主人公の女性がものすごい勢いで出世していく様は正に自己マスタリーの極致といえます。

僕のようにサラリーマンとして生活している人の多くは、ビジョンを大きく持というとせず、瑣末な利害にとらわれて汲々としているように見えます。そしてふたことめには「そうはいってもさ。。。」と絶えず自分に言い訳をしながら、知らぬ間にシステムの囚人となって自分で自分の人生を小さな箱の中に押し込めてしまっているのです。

僕は常々、人生で大切なことは自分が本当に面白いと思うことを一生懸命やることと、明るい未来をイメージすることだと思ってます。

この漫画ではビジョンを実現する女性の姿がほとんど様式美すら感じさせる作風で描かれていて、読んでいてとても爽快です。
一人一人のキャラクターがとても立っているし、泣かせるシーンが満載です。無意味な入浴シーンが多発するのもまぁ愛嬌。
イメージ的には女版サラリーマン金太郎+渡る世間は鬼ばかりといったところでお得感があります。

OSI 12階層のうち、政治層やしがらみ層の問題でへこんでいて、元気になりたいときにおすすめです。

最後に、この漫画の中で僕が気に入ったセリフを引用します。元銀座の主といわれたバーのマスターが主人公にアドバイスをするセリフです。

夢をね・・・
夢をお持ちなさい。
ただクラブのママになるだけじゃなく、こういう店にしたいとかチェーン店で店舗展開したいとか・・・・・
そういう風に夢を描かないとなかなか力は生まれないもんですよ

Almost Plain Text

Maven2のドキュメントのディレクトリにはaptという謎のフォーマットのドキュメントが置かれています。調べてみるとこれは文書をWikiに似たプレインテキストの形式であるらしい。
このフォーマットの文書をいろいろな形式に変換するaptconvertというツールがhttp://www.xmlmind.com/aptconvert.html
から入手できます。
サポートされている出力フォーマットは一応HTML, LaTeX, PostScript, PDF, RTF, DocBook SGML, DocBook XMLと多岐に渡っています。

確かにxdocよりはずっと楽にドキュメントが書けてよさそうですね。

この手のツールは国際化に関する考慮が不十分なことが多いのですが、aptconvertは出力フォーマットがHTML、DocBookであれば文字コードがSJISの入力を受け付けることができます。XML形式に出来てしまえばあとはどうにでもなる話ですから、実用上はこれで十分でしょう。
ドキュメントも充実していて、すぐに使えます。

最強組織の法則

書名：最強組織の法則 新時代のチームワークとは何か
著者：ピーター・M・センゲ
訳者：守部信之
徳間書店 ISBN4-29-860309-X

1995年が初版ということで、そんなに目新しい本ではないです。すこしまえにちょっと紹介した「Agile Management for Software Engineering」という本で重要な参考文献になっていたので、読んでみました。

この本の原題は「The FIFTH DISCIPLINE The art & Practice of The Learning Organization」というものです。直訳すれば「第5の規律 学習する組織の構築の技法と実践」といった所でしょうか。こっちの方が内容を素直に表していて良いような気がします。邦題は何かうさんくさい雰囲気を醸し出していてあまり好きではありません。
原題が示す通り、この本は学習する組織＝ラーニング・オーガニゼーションの構築をテーマにしています。ラーニング・オーガニゼーションとは従来型の階層型かつ権威主義的な組織ではなく、組織を構成するメンバーが自律的に行動し、学習し、成長する組織のことです。現代の企業が市場で競争力を発揮するには、如何にしてラーニング・オーガニゼーションを構築するかが重要であると筆者は主張しています。
ラーニング・オーガニゼーションを構築するには5つの鍵があります。

1. システム思考
2. 自己マスタリー
3. メンタルモデルの克服
4. 共有ビジョンの構築
5. チーム学習

このうち、最初の「システム思考」は特別な存在で他の4つを支えるものです。原題にあるTHE FIFTH DISCIPLINEとはこのシステム思考のことです。
システム思考とは複雑な問題をうまく解決するための物事のとらえ方です。複雑な問題に対処するには因果の鎖を細かくたどっていくだけでは十分ではありません。複雑な環境では原因から結果が現れるまでに時間がかかることと、結果がまた原因に影響を与えてしまうフィードバックループが存在するためです。そのような状況では問題を細かく分割していくのではなく、全体を眺めてなんらかのパターンを見出すとよい、というのがシステム思考の概要です。
こうやってまとめてしまうと抽象的すぎてわかりにくいですが、本書ではもちろん具体例も交えてもっと分かりやすく説明されてます。

全体的に、主張されてる内容はアジャイル開発手法で良いされていることを、ソフトウェア開発から離れて一般的な組織論の立場から述べている点が面白いと思います(本書のほうがアジャイル開発宣言より前なのでこういう言い方はちょっとおかしいかもしれませんが)。このような主張は、アジャイル手法を実際に試そうと、周囲を説得する時に見方になると思います。アジャイルムーブメントが、一部のマニア的開発者のエキセントリックな主張ではなくもっと大きな世の中の変化に呼応したものだということを保守派の人達に説得しやすくなるからです。
ただ、具体的な実践方法となると、やはりほとんど精神論に終始してしまっています。どうやって人がお互いにビジョンを共有するか、とか固まってしまったメンタルモデルをどうやって崩していくか、といった問題は哲学の領域で、実践するには経験的なアプローチしかあり得ないですから、仕方のないことなのですが。頭の硬い保守的な管理者の心の壁を崩すには「経験的にうまくいく」というだけでは簡単にいかないのではと思います。そのような場合は、粘り強く反対派を洗脳していくしかないのでは、と考えています。

タイプ別性格判断

タイプ別性格診断をやってみました。
このblogの主旨とは全然ずれるんですが、たまにはこんなのもありかな、と思います。結果は、

ENTP型：次から次へと挑戦する

あっさり見抜かれているような気がする。。。


ＥＰ型はたいていそうだが、ＥＮＴＰ型も、すでにあるアイデアを実行に移してやり遂げるよりも、新しいアイデアを追い求めるほうが楽しいと思う。

しかも、この世はチェス盤のようなもので、みんながうまくいくように駒をーそれも自分がー動かすべきだ思っている。

とどのつまりは自分だけでなくほかの人も巻き込み、新しいことに次から次へと挑戦する結果となり、悪くすると、きりなく夢を追って中途半端に終わってしまいかねない。

あいたたたたた・・・

とくに古めかしいシステムや人物を相手にすると、ついその限界を試してみるたちである。

(苦笑)いつも御迷惑おかけしております。

もっとも、違うタイプの人をうんざりさせるという点ではかわりない。

ホントすいません。勘弁してください。

簡単なテストで、こんなふうに類型化された性格パターンにあっさりはまってしまう自分が情けない。エニアグラムとかもそうなんですが、この手の性格診断は人格が円熟してくるにつれてそれぞれの性格パターンの要素が入り混じって分類されにくくなっていくものかと思います。まだまだ人生修行が足りないですな。

Agile Management for Software Engineering

洋書なので読むのが遅いのですが、今Agile Management for Software Engineeringという本を読んでいます。
主にTOC(Theory Of Constraints)の観点から、アジャイル開発手法が従来型の手法と比べてどこが優れているのかについて考察しています。作者のDavid J. Andersonは最初にFDDを創り出したプロジェクトのメンバーだった人だそうです。

大きな組織、特に官僚主義的な組織の中で「アジャイル開発をやりたい」と言い出すと、多くの壁にぶつかることになります。アジャイル開発手法はなぜうまくいくかの因果関係はそれほど明確ではないけれども、経験的にはうまくいくと分かっている方法を採用しているので、経営者の視点から見ると開発者が自分が楽しく仕事するためになにやら怪しげな理屈をグダグダこねくりまわしているように見えてしまいます。そして最後には結局「それ、いくらですか?」と言われてしまうのです。

この本はTOCの理論を駆使してアジャイル開発手法がビジネスで利益を生み出す手法であることを豊富な図表と共に解説しています。

後半の章ではXP、FDD、Scrumについてそれぞれ生産性と財政上のメトリクスの収集方法を解説している、と思われます。まだ最後まで読んでいないのでわからないですが。。。

アテネ五輪から目が話せないので、今日はこの辺にしておきます。
さっきもこれ書きながらテレビみていたら、ちょっと目を離したすきに柔道の野村が3回戦で開始14秒で一本勝ちを決めたシーンを見逃しました。腹だたしいことです。

Mojoって何?

Maven2のソースコードを読んでるとそこかしこに"Mojo"という単語を見かけます。これは一体何なのでしょうか。

maven-core/docs/apt/mojos.apt

の記述によると、MojoとはMaven java objectsのことなのだそうです。"Mojo"の最初の"o"はどっから湧いて出たんだ!と突っ込みたくなりますが、誤解を恐れずにものすごく平たく言うと、一つのゴールを実行する責務を負うJavaオブジェクトというくらいの位置付けの様です。(間違ってたらご指摘ください)
例えば、maven jar pluginは

AbstarctJarMojo.java
JarMojo.java
JarDeployMojo.java
JarInstallMojo.java

という4つのJavaファイルから構成されています。AbstractJarMojoは抽象クラスなので、実質3つのMojoですね。そして、JarMojoはjarというゴールを実行するという具合にMojoとゴールは1対1の関係にあります。ですから、Maven2のプラグインはMojoのかたまりといえると思います。

面白いのは、個々のMojoが自分担当するゴールに関するメタデータをXDoclet風のJavaDocタグの形で保持しているという事です。
例えば、JarMojoのクラスコメントは以下のようになっています。
/**
* @goal jar
*
* @description build a jar
*
* @prereq surefire:test
* @prereq resources:resources
*
* @parameter
* name="jarName"
* type="String"
* required="true"
* validator=""
* expression="#maven.final.name"
* description=""
* @parameter
* name="outputDirectory"
* type="String"
* required="true"
* validator=""
* expression="#project.build.directory"
* description=""
* @parameter
* name="basedir"
* type="String"
* required="true"
* validator=""
* expression="#project.build.output"
* description=""
*
* @author <a href="michal@codehaus">Michal Maczka</a>
* @version $Id: JarMojo.java,v 1.10 2004/07/07 07:18:10 evenisse Exp $
*/
public class JarMojo extends AbstractJarMojo

見れば一目瞭然、ゴールの名前、説明、パラメータの名前、型、説明、パラメータが必須かどうか等の情報が書かれています。
これらの情報はmaven plugin plugin を使ってプラグインをビルドする時に、プラグインのjarのMETA-INF/maven/plugin.xmlの中に書き込まれます(多分ここでQDoxを使っているのでしょう)。
そしてこの情報はorg.apache.maven.Mavenインターフェースを経由して取得できます。これはeclipseなどのIDEにMavenを組み込む時にとても便利そうです。

JavaDocタグとして記述される情報の中で注目したいのが、@parameterにくっついている"expression"です。
ここでプログラム中から参照されるパラメータ名と実際に使用されるオブジェクトを紐づけています。V1ではプラグインのパラメータはほとんど全てシステムプロパティに設定されていましたが、Maven2では"expression"に指定された評価式をベースにOGNLを使用して取得されます。
OgnlProjectValueExtractorというクラスがOGNLを使って値をとってくる役目を担っています。

Mojoに関してはmaven2のメインのCVSにあるものの他にCodehausの中でもいくつか開発が進められているものがあるようです。
(http://cvs.mojo.codehaus.org/からソースが見れます。まだ準備中みたいですが、http://mojo.codehaus.org/というのもあります)

テストケース vs DbC

XPでは特に、テストケースが仕様書の意味も持つと言われます。
これとDbCの事前条件/事後条件によるコントラクトはどちらが優れているのでしょうか?

これはきちんと考えると意外とややこしい問題だと思います。Martin Fowlerはこの問題に対して興味深い意見を述べています。

DbCでは一般的なルールとして仕様を記述しますが、ちょっと難しいことをやろうとするとものすごくトリッキーなコントラクトを書かなくてはならなくなります。これに対して、テストケースではAPIの使用例が仕様の代わりになるので記述は簡単になります。
その代わり、仕様としての厳密さは失われるし、アサーションコードは煩雑になります。DbCの方がすっきり書けるケースも確かに存在するのです。

使われる状況を考慮にいれなければ、どちらが良いということはいえないと思います。現実的に考えた場合、仕様を理解するには使用例と、一般的なルールのどちらも必要です。新しいライブラリを使いこなすには、最初はコード例を見た方が早いでしょうが、完全に使いこなすには一般的なルールを知らなければなりません。コード例だけだと、そこから一般的なルールを頭のなかでリバースエンジニアリングしなければならなくなるのです。

XPのようにチーム間のコミュニケーションがうまくとれている場合、一般的なルールは暗黙のうちにチームのメンバーが了解しているので、正しくインターフェースを実装することができるでしょう。
従来型の開発手法を採用している組織では完全な仕様を記述する必要があるため、DbCのようなアプローチを採用する必要があると思います。

テストケースを使用例とするなら、一般的なルールは実装コード自体になります。あの「コードは仕様だ!」という奴です。
これは実装コードがきれいにかかれており、プログラマの意図が明解に示されている場合のみ成り立ちます。

DbCではこれに加えてエラーが起こったときに誰が悪いのかを簡単に特定できるというメリットがあります。ただし、その代償として多少の冗長さを必要とすることは否めません。コントラクトはほとんど実装コードと同じくらいの長さになってしまうことが良くあります。現状、テストケースにおけるJUnitのようなデファクトスタンダードとなるツールがないのも問題です。

結局最終的な結論は出ていないのですが、個人的な好みとしてはいまのところDbCの方が好きです。最近結構DbCについて勉強しているのでバイアスがかかった見方だとは自分でも思いますが。。。

皆さんはどう思いますか?

Subversionの活用案

いま関わっている仕事のドキュメント管理にSubversionを使ってみようかと思って、マニュアルを眺めているうちに、これはいろいろと面白い使い方が出来そうだと感じました。CVSと比べて良いのは、svnlookを使ってリポジトリの状態(特にディレクトリツリー全体に関わるもの)を細かく調べられることと、バージョン管理下のファイルやディレクトリ、リビジョンに"属性"という名前つきの値を付与することができることです。

これらの機能を上手に使えば成果物管理につきもののめんどくさい作業をちょっと自動化して楽に出来そうな感じがします。と言うわけで以下にアイデアを書きます。

1.成果物一覧の自動生成
svnlook treeの出力を解析してExcelに張り付ければ簡単にできそうです。属性として各ファイルに短い説明を付けておけばそれも一緒に表の形で表示できて良いでしょう。

2.変更履歴の自動生成
コミット時に変更されたファイル、その変更内容、変更者の情報をその都度どこかにとっておいて、あとでマージすることで自動的に生成できそうです。もちろん全リビジョンの情報をあとでまとめて取得しても良いでしょう。最終更新者、最終更新日などの情報は成果物一覧にマージして表示してもよいかもしれません。

3.変更の影響範囲の追跡
各ファイルに属性として自身の変更によって影響を受ける可能性のあるファイルのリストを保持しておき、そのファイルが変更されたときに、「影響を受ける可能性があるファイルとの整合性をチェックしてねー」という旨を関係者に通知できたら面白そうです。

1, 2 は簡単そうですが、3は少しめんどくさそうですね。

解剖! Maven2

やっとMaven2のソースコードを入手できたので、時間を見付けてちょこちょこと読んでいます。まだまだ開発途上といった感じなのですが、大体何をやろうとしているのかは分かります。
Maven V1のソースコードは1行も残っていないのではと思います。

Maven2の一番の特徴はPlexusというDIコンテナを使ったコンポーネント指向のモデルを採用している点だと思います。
Plexusが他のDIコンテナと比べて特徴的な点はField InjectionというDependency Injectionの方式を推奨しているところです。
これは、プライベートフィールドに直接依存コンポーネントをInjectしてしまうというかなりきわどい方式です。おかげでMaven2のソースコード中にはどこで初期化されているのか分からないプライベートフィールドが多発しているため、直接Injectされていることを突き止めるまでは相当悩みました。
正直なところ、Field Injectionを前提としてクラスを設計してしまうと、もはやそのクラスは普通のJavaオブジェクトとしては使えなくなってしまうので、イマイチなんじゃないだろうか?と思っています。Plexus自体は一応Constructor Injection/Setter Injection共にサポートしているようです。

Plexusの設定はjarファイル中のMETA-INF/components.xmlに記述することになっている様です。添付の画像はmaven2のコア部分を構成する主要なコンポーネント間の依存関係を示したものです。
コンポーネントは互いのインターフェースにのみ依存しています。
Maven自体もコンポーネントになっているので、他のツールへの組み込みはV1の時より随分楽になっていると思います。

V1の位置付けは基本的に「Antスクリプト再利用フレームワーク」で、スタンドアロンの利用を前提としたものでした。
例えば、mavenをサーバ側において、サーブレットと同一VMで起動したい場合、普通にmavenの中でSystem.exitをやってくれているため、maven終了と同時にTomcat終了という事態が発生ていました。

maven2では少なくともそういう事はなさそうです。
プラグイン自体が、従来はプラグインリファレンスのWebサイトにのみ掲載されていたような、自分自身の使い方に関する情報を持てるので、IDEとの統合もずっと楽そうです。

maven2はAntスクリプト再利用という枠を越えてもっと汎用的な何かを目指そうとしていると思われます。