文書の品質を作り込む難しさを乗り越えるために

プロジェクトでは、提案仕様書にしても、受注した後の要件定義書、基本設計書(外部仕様書)、詳細設計書(内部仕様書)、テスト計画書や各フェーズで顧客とプロジェクトのスコープである要件の聞き取りやシステム仕様の整理などのさまざまな文書を作成し、顧客と取り交わし、共通理解を積み重ねてソフトウェアを作ることになるのだけれど、トラブルが起きるプロジェクトは、何らかしかの文書の品質が悪いことが多いです。

品質が悪いと書けば一言で済んでしまうのだけれど、実際の現場ではたまったものではなくて、それこそwar roomになったり、誰が何をやっているのかさえ見通しが出来ないくらいになっているものです。

例えば、提案仕様書の書き方が曖昧なところがあって、そのあたりの顧客要求もゆるゆるだと危険極まりないのです。なぜならば、提案仕様書の書き方が曖昧だからこそ、顧客は都合よく提案仕様書を解釈して曖昧な範囲を広げようとするからです。

ITエンジニアリングでの文書の品質とは、それこそ顧客の文書の品質要求と契約の縛り具合で千差万別ですが、どのような文書であっても共通して文書の品質を作り込むことができるのではないかと思うのです。

目次構成
文書を作るからには、次工程のインプットとして必要な情報を網羅的に充足する必要があります。そのためには、文書を構成する目次を抜け漏れが生じないように、どのようなプロジェクトでも共通的な候補から、当該プロジェクトに不要な項目を落とすようなテラーリングする方法がよいと思います。

そのためには、過去のプロジェクトのdeliverableから目次を抜き出して、ノウハウとして溜め込むことが必要です。「でもねぇ、目次を抜き出すワークが取れないんだよ...」と言うのであれば、文書をただ溜め込むことをするだけでも、そこを見れば過去資料として参考にインプットできるので大分違うものです。

兎に角、「自分の頭の中だけで文書の目次を構成しない」ということです。ヒトの頭は、すべてを記憶するアプリではないということを忘れずに過去の文書を再利用し、“常に、網羅的に”と言う意識を持って文書の構成に当たることが肝要だと思います。

章節項の記述レベル
実際に文書を書くときに、文書としての品質を均一に得たいのであれば、プロジェクトのメンバが書き始める前に標準化をすることが必要です。もし、書き手が書き始める前に標準化を申し伝えなければ、書き手は自己流で書き始めるものです。

システム開発で新技術を適用するときに技術検証やプロトタイプをするように、プロジェクトチームで文書を作るときは同じように文書として書き記す文章の表現レベルをお手本として作り、メンバの意識レベルを合わせた方がよいでしょう。これをしないと、後出しで標準化することになるので、メンバの立場から言えば「最初に言ってよ〜。」だし、文書をレビューする顧客にとっても「何でチームで作っているのに記載レベルがバラバラなの？」というフラストが溜まるばかりです。

用語と“てにをは”
その文書で使用する用語、特にシステムの機能などの用語が統一されていない文書は以外と見かけるものですが、読み手の立場から言えば、不信感を買ってしまうこともあるのです。実際、機能仕様として問題が無くても、用語が統一だとか、てにをはや助詞、接続詞が出鱈目だと読むときに読むリズムが引っかかるので、どうでもよいところにケチが付くことになります。

用語については、辞書に登録することで統一することが出来るけれど、辞書を作りそれをメンバに登録させて使用を徹底する手間を惜しまなければなりません。でも、後からレビューなどで駆除することよりはよいでしょう。

ところが厄介なのは、てにをはや助詞です。wordなどのオフィスツールならおかしな助詞を使うと文字の下に赤の波線が表示されるのでそれで気づくことが出来ますが、そもれ気づかなければ誰かが気づくまで先送りされてしまうのです。

これを機械的に駆除したいのであれば、Just Right!