ドキュメント指導

 今日は若い衆に設計書の書き方をレクチャーしたが、なかなか難しいな。(´・ω・`)
どうしても、記述が安定しないんだよね。

「安定しない」とは何か？
例えば、項番のタイトルだ。

• 契約情報の更新：契約テーブルを契約番号で検索する。

これは検索処理なのか、更新処理なのか、どっちなんや。
項番のタイトルと中身が尽く違う。

これね～、うっかりミスならしゃーないんだって。設計書の修正を行っていく中で修正漏れがあった、とか、そういうのは起きうるからね。
でも、こういうのが僅かな分量の中に１０も２０もあったら、それはミスではなくて、そもそも思考出来ていないと見做さざるを得ないよね。

安定しないのは他にもある。

設計書の上の方では「OK / NG」って書いてあるのに、下の方に行くと「NG / OK」と昇順降順のセンスが入り乱れるとか。

「※特記事項」と書かれているけど、特記事項でも何でもない。単なる分岐の一つ。特記事項と特記事項ではないものの違いが分からない。

「処理結果が不正な場合、エラーとする」
エラーとするって、何をするのか？　正常な場合は何をするのか？
本来はこう書かなければならない。

• 処理結果が不正な場合、エラーログを出力して処理を中断する。
• 処理結果が正常な場合、処理を継続する。

無論、「エラーの場合に処理を中断するのは暗黙の了解だし、正常な場合にそのまま次の処理に進むのも暗黙の了解だ」と言うのであればそれも一理あって、その指針の元で書かれているなら良いけど、設計書の場所によってはちゃんと書いていたり、書いていなかったり。
ちぐはぐ。

こういう事象が入り乱れて山盛り発生する。
安定しないとはこうい意味だ。

とは言え、実はこのパターンは若手は過去に何人も見た事があって、決して珍しいものではない。
珍しい話ではないんだけど、どうしてこうなっちゃうのかな～。
それが分からん。

(´・ω・`)「設計書の上の方と下の方は、同じ言葉で書くようにしようね」

って、そんなこと説明しなきゃならなんような話ではないと言うか、何でそうなる？

人間とは無意識にいつも同じ言葉使いをするものではないのか？
何でコロコロコロと言葉使いが変動するんだ？

何故だ。何故こんなことになるんだ。

分からん。(´・ω・`)