ダメな設計や手順書の作成に至る原因は何に起因するのだろうか

ありますよねー。一目見て「だめだ、この設計書。」とか「おいおい、キミはこれで何を構築しようとしているんだい？」と思う設計書とか手順書とか。それってそのまま進めてしまっては、あとあと手戻になることは確実だし、程度によっては設計を一からやり直し！なんてことになりかねない。時期によってはそんな祖先帰りまでできないのでハウルの動く城のごとく増築に増築を重ねて何が何だか作った本人たちでさえわからなくなってしまうことに。ひとつ違うのは、ハウルの動く城はカオスに見えるけれどきちんと機能しているが、エンジニアが構築するシステムは機能しないものや意図した動きをしないことがあるということだ。

目次がダメ
ドキュメントを読むにあたってそれが設計書であるなら目次を見れば程度がわかるものです。目次の構成、章節項の章節あたりの階層構造をみればどこの範囲まで書こうとしているのか、大体察しはつきますよね。要件、機能、非機能、障害時などを展開方法と節レベルでのカバレッジで抜け漏れがあるかないか、そうした観点で眺めるとアレがない、とかコレがない、とか直感的に導き出されるという塩梅です。

そうしたドキュメントの構成はプロジェクトマネージャ、アーキテクト若しくはPMOが何処から見つけて持ってくるか、そうしたテンプレを気まぐれで作って展開することが多いです。つまり、そうしたテンプレを用意する人たちが設計書がダメになる原因を作っていると言えます。

じゃあ、すべての原因がそこか？と言えばそうでもなくて、項以降を展開するエンジニアが体系的に機能を分解して書くことを書かないとやっぱり章節までは良くても実はその設計書をインプットにする後工程や対抗になる試験工程のアウトプットに爆弾を仕込むことになるんですね。だって、抜け漏れや間違いがある仕様でシステムを作って、その仕様をインプットに機能試験の仕様を組み立てたってそんなの意味がないでしょ？そういうことです。たまたま試験計画や試験仕様を担当するエンジニアが優秀なときにインプットの設計がダメだと発見できたらそれはそれですばらしいことなんだけれど、試験工程に突入しているので残り時間がないので取れる手段が限られる。その結果、場当たり的なつぎはぎの対応になったりするわけです。

設計書の目次は、最後まで影響します。よく考えて目次を設計しましょう。

手順が確立していない
おかしな標題ですが。手順書なのに手順が確立していない、なんて。でもね、あるんですよ。そういう手順書。手順書って、誰を読み手と想定して作るものでしょう。その手順書を作成したエンジニアだけ、ですか。それともチームのメンバまで、でしょうか。それとも構築したシステムの技術要素まで知らない運用担当者だったりしませんか。

ときどき見つけちゃうのが構築手順書で操作の遷移で全部の手順が正常に進む前提で作っている手順書です。それって拙いですよね。なんで正常にしか手順が進まないのでしょうか。正常に進むには使用するコマンドやインストーラの前提条件がすべてクリアされていることが前提になります。それ、その手順書で作業前に確認させていますかね？とかあるのにそれも確認せずにいきなりインストーラをクリックして、みたいな手順書があるほんとビックリしちゃう。

それ暗黙じゃだめでしょ。操作する人が必ず手順書を作成した人ならいいんですよ。でも、その作業する日に確実に行ける保証ってとこにもないでしょ？ちょっとでも考えたら、じゃあ、メンバがやるかもって想定できるんです。そして、暗黙はなくして手順を書く。だって、そうしないと作った人に結局聞かないと進まないんですから、

同じように、手順書がすべて正常に遷移することを至上とする手順書を見つけるときがあるんです。それもワタシ的にはダメ。だって、環境に依存して進まなくなっちゃうことだってあるじゃないですか。そのくらい想定してくださいよ、と思っちゃう。コマンドの結果がエラーだったら？インストーラで指定したあとの処理がエラーになったら？

手順書を作成するということは手順を確立するということです。