Ognacの雑感

木漏れ日々

目次

Blog 利用状況

書庫

ギャラリ

「マニュアルや仕様書は判りやすく、誰にも正確に伝わるように記述しましょう」....は限界があります。

対象となる読者対象によって記述レベルを変えるのは自然です。
ベテランから初心者まで、平等に伝える必要があるか.......私は無いと思うのです。要件定義書は、意思決定者向けで、開発レベルは記述しません。業務的な効果を書くことがあります。開発者には不急の事項もあります。
開発者向けの詳細仕様書の内容を上流工程者に伝えるのは、労力の割には報われません。
 対象を絞って記述レベルを変えるのは、マナー違反にはならないと考えます。

違う面ですが、「抽象的で主観的な記述はダメ」と言われます。ある機器の動作環境の項目で

 動作保証温度 xx度~xx度
 動作保証湿度 xx%~xx%
 埃           特に酷くないこと

とありました。
「特に酷くないこと」という主観的な表現は、"どうなん"と思う一方で、他に表現できないなぁと思うのです。
 埃の厚さが0.5mmを超えないこと...とは書けないでしょうし。
埃感知器の存在は知らないのですが、 1立米あたり xx ppm や xx mgの測定結果で判断できそうですが、測定器が手近にありそうにないです。
測定できない数値を掲示するよりは、「特に酷い」と表現するほうが、正直な気もします。

 完全な表現を追求した結果、読みにくく、誤解を与える文面より、主観的でも、理解を得られる表現の方が、より正しく伝わる局面も在りそうです。
 
 マニュアルは、正確性と機能を網羅したいという思いから、分厚く、項目も利用度に関係無く、頻繁に使う機能と滅多に使わない、一回も使わない機能が同レベルとして書かれていることが多いです。
 初心者向けマニュアルとして、頻度の高い機能だけの冊子。
 中級者向けマニュアルは、中程度の頻度の冊子。
 ベテラン向けのマニュアルは、機能の辞書的な本。
最近の製品は、このように複数種類のマニュアルが付いてるのも増えましたね。

開発者向けの自習書は、頻度が考慮されていないのか、熟練してから、知ってもいいような項目が、初級段階で登場する本を見かけます。それが、学習者の足を引っ張ることもあります。
「人を見て法を説け」とは良く言ったものです。 (前回の私のコメントの流用...www)

投稿日時 : 2008年12月24日 7:20

Feedback

# re: 「マニュアルや仕様書は判りやすく、誰にも正確に伝わるように記述しましょう」....は限界があります。 2008/12/24 11:13 774RR

仕様書とマニュアルは違うっす。
マニュアルは読者層を想定して書くのが当然。
ハンバーガーの焼き方マニュアルと売り方マニュアルは書き方が違って当然。

仕様書、特に内部仕様書って直接開発担当者以外読まないと思うんだけど、違います?
> 詳細仕様書の内容を上流工程者に伝えるのは、労力の割には報われません。
読ませる必要の無い相手に読ませる文書を作っているのだから、それはある意味当たり前なのでは。

難しいのは外部仕様書、だと思う。
誰が読みうるのか?を考えて書くのは当然なんだけど、冗長になったり不足したりと難しいっす。

最近はノウハウ伝達をかねて冗長に書くほうを選んでますが。

# re: 「マニュアルや仕様書は判りやすく、誰にも正確に伝わるように記述しましょう」....は限界があります。 2008/12/24 13:25 ognac

要件定義書 => 外部設計書 => 内部設計書 => 詳細(ロジック設計書)=> コーディング

とした場合、読者層は限定されるので、書き易いと考えてました。
あるプロジェクトでは、内部設計書までは、客先納品レビューの対象となり、コードを書かない客先担当者が受領チェックするそうです。....理解できないものを受領チェックできるのかも含めて、冗長な作業になったそうです。
ウォータフォールの流れを組む設計方針の一部に、要件定義を砕いたモノが外部設計で、更に砕いたモノが内部設計だとする思想が現存します。
この思想では(納得はしてませんが)、要件定義に登場する項目は、外部設計の項目になり、項目は、内部設計の節になる。
上位で登場した言葉は、下位で登場しなければ成らない...とありました。

内部設計は、製造者向けのモノだから「おかしいのでは」と議論したことがあります。
外部設計から、作成する本数が決まるのて、「内部設計がかけ離れたモノになるのはおかしい」と...何時までも平行線。
 #妥協した私....orz;
これだと、OOP手法などの継承関係等を持つ製造物の内部設計書は書けなくなりそうな気がするのですが..www;

「書いても、どうせ読まれない」という意識があると、仕事が疎かになるのも事実で、作業効率と成果物の役割と使命を各過程の人の認識が必要なんでしょうね。 工数(仕事)の無駄使いと感じるのは私だけ?

# re: 「マニュアルや仕様書は判りやすく、誰にも正確に伝わるように記述しましょう」....は限界があります。 2008/12/24 22:48 Pasie.

あくまでお出しするのは料理であってレシピではありません。と強く出てみる(ぉ

# re: 「マニュアルや仕様書は判りやすく、誰にも正確に伝わるように記述しましょう」....は限界があります。 2008/12/24 23:26 インドリ

そもそも、全人類に同じメッセージを伝える文章がかけないのに、そんな無敵な仕様書けないピヨ♪
でも昨今は、読み手のレベルを限りなく低く見積もって、とにかく書けばいいという風潮があるみたいだピヨ。
でも、余計な文章で必要な情報が埋もれてしまうのも外だとボクは思うピヨ♪

タイトル
名前
Url
コメント