Lazy Diary @ Hatena Blog

PowerShell / Java / miscellaneous things about software development, Tips & Gochas. CC BY-SA 4.0/Apache License 2.0

エンタープライズアプリケーションの開発ドキュメント作成で気をつけていること

エンタープライズアプリケーション*1を開発するときに、開発方針(従うべきアプリケーションアーキテクチャの説明から、ライブラリ的なプログラムの使い方までいろいろ)を文書化する役目がよく回ってきます。

「このライブラリにはどういう機能があるの?」「この機能はどう使うの?」を中心に書いた一般的な技術文書と、エンタープライズアプリケーション向けのドキュメントとでは、書くべき内容や書くときに気をつけるポイントがずいぶん違うなぁ(しかもあんまり明文化されてないなぁ)と思ったので、エンタープライズアプリケーション向けのドキュメントを書くときに必要な内容をメモしておきます。

ドキュメント体系に追加する

プロジェクトのドキュメント体系に含まれていない資料は、プロジェクトの正式なドキュメントではありません。正式でないドキュメントの内容に基づいて実施した行動の責任は、誰も肩代わりしてくれません。責任はすべて自分がとる必要があります。イヤですよね(そうでしょう?)

ドキュメントを作成するときは、まずドキュメント体系に追加しましょう。プロジェクトの体制中に、ドキュメント体系の保守を担当しているチームがあるはずです。なかったら、プロジェクトマネージャーに報告して、プロジェクト管理計画を修正してもらいましょう。

ドキュメント体系の編集が面倒*2な場合は、既存のドキュメントの「別紙」とか「付録」とかにすることを検討しましょう。よく、プロジェクトの共通ドキュメントに「別紙」が大量にあるのを見かけますが、これが理由というケースが時々あります。

対象読者を書く

プロジェクトのメンバーには、目を通さなくてはいけないドキュメントがいっぱいあります*3。そんなメンバーが、ドキュメントについてまず知りたいことは「これ読まないといけないの?」「これ知らないといけないの?」です。この点が示されていないドキュメントは、一目だにされないこともしばしばです。

ドキュメント体系には、対象読者も合わせて記載しましょう。分量の多いドキュメントでは、章ごと・節ごとに対象読者が分かるアイコンを付けるのも効果的です。

使わないといけないか書く

ここで「使わないといけない」というのは、「あなたが責任を負う成果物を作成する際には、このドキュメントに書いてある内容を守らなくてはいけない」という意味です。

「これ知らないといけないの?」をクリアしたら、次は「これ使わないといけないの?」「これ使わないとどうなるの?」が主要な関心事になります。「知らないといけない」けど「使わなくてもいい」ものなんてあるの?と思うかもしれませんが、たとえばトラブルシュートや、問題発生時の原因切り分け手順などがこれにあたります*4

なお、ちゃんと「これ使わないといけないの?」が分かるドキュメントを作っていても、「これ使わずに作っちゃったんだけど、許してもらうにはどうしたらいいの?」と言われることもしばしばです。避けたい状況ですが、これも文書化しておきます*5。また、将来のために「これ使うのをやめたいんだけど、何をどうカバーしたらいいの?」が必要になることもあります。

誰の責務か書く

「これ使わないといけないの?」に対する答えは、大きく分けて「はい、この処理の実装はこのライブラリの役割です。このライブラリを使ってください」と、「はい、この処理の実装はビジネスロジックの役割です。あなたが実装してください」に分かれます。

エンタープライズアプリケーション開発のプロジェクト体制では、アーキテクチャの検討や業務色のないフレームワーク・ライブラリの実装を行う「共通チーム」と、ビジネスロジックの実装を行う「業務チーム」とを、比較的明確に分けられます。

この場合、フレームワーク・ライブラリとビジネスロジックとの境目を決めて、どの処理の実装がどのチームの責務なのかを明確に示すことが肝要です。そうしないと、この間に落ちてしまった処理を誰も実装しないままプロジェクトが進んでしまい、共通チームと業務チームとの間で責任の押し付け合いが始まります*6

何のための機能か書く

フレームワークやライブラリに「どういう機能があるの?」「どう使うの?」を書き始める前に、「何のための機能なの?」を示しておいた方が安全です。業務チームのメンバーが、どういう時にこの機能を使えるかを知るための取っ掛かとなります。また、ライブラリの開発者の意図を伝えることで、想定外の使い方をされてしまうのを避けることができます。これは、業務チームのメンバーがマズい実装を作り込んで、プログラム不良が頻発するのを避ける効果があります。

場合によっては「何のための機能ではないか」を書くこともあります。ライブラリの開発者の意図を伝えても、使いたいように使ってしまう開発者というのはどうしてもいるものです。既知の制約がある場合は、明示しておくことでライブラリの開発者を無茶な要求から守ることができます。

機能や使い方を書く

ここまで来て初めて「どういう機能があるの?」「どう使うの?」を書くことになります。

使っていること・いないことの調べ方を書く

必要に応じて「この処理を必ず書かないといけないなら、書いていることをどうテストするの?」「この処理を書かないといけないのに書いていない(ルールを守っていない)ことは、どうやったら調べられるの?」が分かるための資料も作ります。

テストで確認すべき観点*7や、チェック用の静的解析ツールの使い方と警告メッセージを示します。

場合によっては「このアプリケーションの開発で守らなければいけない点はぜんぶでいくつ?」が分かる資料を求められることもあります。これは、業務チームを取りまとめる責任者が、自分のチームの成果物をチェックするための手順として求めてくるケースがちょいちょいあります。

*1:ここではいわゆるギョーミーなソフトウェアを想像してください

*2:ドキュメント体系を体系図として視覚化している場合はとっても面倒

*3:To do our work, we all have to read a mass of papers. (Winston Churchill)

*4:成果物の作成に際して前もって読んでおく必要はなくて、トラブルに遭遇したら必要な部分だけをその都度読めばいい

*5:文書化しておかないと、後任者が見たときに、問題があるんだかないんだか分からなくなります

*6:【余談】誰の責務で実装するか決めるときの私なりのコツは、何でもフレームワークで面倒を見るよりは、業務チームがビジネスロジックで実装する(あるいは、ビジネスロジックからライブラリを明示的に呼び出す)側に寄せることです。この際、多少ステップ数が増えても構いません。

業務チームは人数が多いため、アーキテクチャに対する理解を全体に浸透させるのに手間がかかります。ビジネスロジック中に、フレームワーク的な処理も一部含めて実装するのは、コードを「上から見ていけば、必要な処理が一通り書いてある」状態にでき、アーキテクチャを理解させやすくする効果があります。またフレームワーク的な処理に変更が必要になった場合、実装の変更とテストの両方が業務チームに閉じることから、業務チームの判断で作業を進めることができ、業務チームの人数の多さもあってリカバリーが効きやすくなります。

増えてもいいステップ数の「多少」がどの程度かは、システムの保守期間、アプリケーションの総ステップ数、プロジェクトのリスク費の大きさなどを見て決めます。総ステップ数が1%増えるだけならいいですが、5%増えるとなると考えものです。

*7:加えて、その観点を何の単位(画面単位で1度テストすればよいとか、イベント単位にテストする必要があるとか)でテストするかも必要です