つれづれなる技術屋日記

しがない技術屋。専門は情報工学で、「つれづれ技術屋」って呼んで。

ドキュメント作成やレビューでのイライラ

最近、自分の資料作成や他人の文書レビューに参加して、ちょっとイライラ。自分や相手そのものへのイライラではなくて、文書がうまくまとまっていないとか、ロジックがおかしいと感じてのもの。「そういえば」と、とあるプロジェクトでの様子を思い出した。他のプロジェクトでも大なり小なり発生。むしろ、設計書作成や設計ドキュメントではイライラするくらいが正常と思うようになった。

どういう事かというと、ドキュメント作成時には、そもそもどうまとめるかで議論沸騰。章立てを決める前後は、どこに何を書いた方が良いか悩みが発生する。章立て(見出し)の階層レベルをどうするかも、キーポイントになる。しかも章立てしながら、新しい要望や実装に関する制限が頭に浮かんだりする。

実は、要求工学とか要求開発で、その辺りが知識体系(BOK)として明快な答えが得られるかと思ったけど、無理そうだ。要求開発とかでの妥当性確認(validation)とは、整理された要求項目がユーザ要求と合致しているかとか、ソリューションがユーザ要求と合致しているかの確認である。後者では、元々のユーザ要求というよりも、合意されたなり設計上のユーザ要求と考えて良いだろう。

ちなみに、一般的に「実現性確認」という言葉もあり、ユーザ要求に対するシステム設計が実現できるかの確認を行う。通常は、実現するためのコストなども加味した確認を行う。

当初書いたイライラや悩みは、製品開発の初期にどうのような製品にするかも漠然としている状況で、言わば実現性も検討しながら製品仕様をまとめ上げる過程での悩みである。(ITシステムだと、むしろRFP(提案依頼書)をうまくまとめ上げる作業での悩みに近い。)

小説や映画(文書としては台本というべきか)での生原稿で、いくつも朱書きがある状況がイメージしやすいかも知れない。その後、いく度も推敲を重ね、編集や校正の人の手を経る事になる。

上記で章立てと書いたが、設計とか提案依頼書の作成は複数人で行う事も少なくないので、その作業分担も関することも悩むところである。複数人での作業では、記述の詳細化レベルや表現もばらばらなこともあり、読む側にとってはそれらも気になる。(かと言って、それらの整合性のために余り多くの時間を割くわけにも行かないというのが実情だ。)

逆に、ドキュメントを小さなボリュームの文書に分割して、各々を一人程度で作成することが行われる。それぞれの文書を、それぞれレビューする事が多い。個人的な見聞きでは、大枠が決まってない状態でこれをやると、作業は進んでいるように見えても、ほとんど後々うまく行かなくなる。

設計書や提案依頼書のまとめ上げ方は、案外その組織体での大きなプロセス資産だと思うのだが、どうだろう。

蛇足1:後付でドキュメントを書くことがある。特に多いと感じるのは、システムのちょっとした変更だが実装による制限発生とか使い方での注意点の追記記述。良い例か分からないけどタイムリーなのは、2013年3月のIC乗車券の全国相互利用だろう。システム的には微細な変更だろうが、利用者に分かりやすく説明したり制限を正確に記述するには大変な作業と思われる。設計サイドで書くよりも、ライターとか品質部署の目線での記述が良いかもしれない。あるいは、設計含めたそれら複数グループの協業。

蛇足2:仕様の抜けや漏れが無いようにと言うけど、新製品の適用市場や対象ユーザの想定における抜けや漏れへの意識/(ちょっとした)対策も、結構役立つことがある。

©2005-2020 ほんだ事務所(honda-jimusyo) All rights reserved.