(作成中) アジャイルExcel-想定する文書作成(2) 表現形態

2022年9月25日

アジャイル開発において必要となる文書は、ウォーターフォール開発でのそれを簡略化したものになると先に述べたが、単に簡略化するだけでなく、以下の点を心がけるべきである。

ページコンテンツ

文章より図や表

アジャイル開発における文書化は、リスト・表・図を中心とすべきである。

図や表の作成には、文章よりコストを一般に要するが、以下の特性からすぐにペイする。逆に言えば、文章中心の技術文書は技術的負債となる。

情報伝達コストが低い

平たく言えば、伝わりやすい、記憶に残りやすいので話が早くすむ。一方、文章中心の場合、そもそも読んでもらえないことが多い。

流用性が高い

図や表の場合、そのまま顧客などへの報告や新規参入メンバーへの説明に用いることができる。一方、文章だけの場合は、新たに説明資料を作成する必要が生じ、二度手間かつ二重管理となる。

品質が向上する

二次元に展開することで周辺と比較がしやすくなり、矛盾や誤りが浮き彫りになることから、文書の品質向上に繋がる。一方、文章だけの場合、言い回しなどの非本質的な問題が気になり、論理性、一貫性など本質的な問題がおろそかになりやすい。

変更しやすい

表はもちろんのこと、文章と比較して図は意外にも変更しやすい。

文章を変更する場合は、一旦論理構造を抽出し、そのレベルで変更し、再度文章に変換するという実は高度な作業を行う必要がある。これはエンジニアに多い、作文が苦手なメンバーだけでなく、文章作成に慣れた人間でも億劫な作業となる。特に他人の書いた文書であればなおさらである。

 

状態遷移図を活用

複雑化したシステムの挙動を直感的かつ簡潔に表現可能

ソフトウェアシステムの進歩は、シーケンシャル処理⇒GUIやサーバのようなイベントドリブン処理⇒複数のサービスがインタラクションするクラウドシステムのように、その振る舞いが動的かつ複雑化していく流れにある。

このような動的な振る舞いを直感的かつ簡潔に表現できるのが状態遷移図である。

状態遷移図には以下のようなメリットがあり、アジャイル開発においては不可欠な図だと考える。

設計品質が向上

二次元に思考が展開されることで、粒度やネーミングの不統一や、例外処理などの抜け漏れに気づきやすくなる。

また、簡潔かつ直感的であることから設計に多くの人を具体的で建設的な議論に巻き込むことが可能となる。

下位工程に規律をもたらす

状態やイベントを定義することで、詳細設計やコーディングに適度な枠をはめ、テストに状態遷移の網羅という一つの基準を設けることができる。

 

気を付けるべき点

ネーミングには細心の配慮を

影響範囲が大きいためである。ネーミングは、下位工程だけでなく、ステークホルダーの正しい理解にも影響するためである。そのため、プログラミングにおける変数名・関数名以上に配慮が必要となる。

適度な階層化

その文書を用いて、自分に対してプレゼンできるかを考えてみる。

上位文書との一貫性を常に維持すること

設計の問題に早い段階に気づくことができるためである。また、矛盾のあるものは使われなくなるためである。

Posted by urojima