『実践！システムドキュメント徹底活用』を読んでみた

とあるシステムの設計書が無くて保守性が著しく低い業務がありました。

そこでソースコードから設計書を起こしてもらい、それをレビューするときに

どのような設計書が良い設計書なのかを見直すためにこの本を読んでみました。

【要旨】

・設計書は読み手の思考を考慮して作成する

・設計書は誰に何を伝え、何をしてもらうためのものなのか明確にして作成する

・システム設計表現は5w2h

【今後のアクション】

・機能表現を使ってみる

・魔法の6マスを使ってみる

【個人的なほぼ抜粋メモ】

1.文章力の3つのポイント

　文章力：相手の思考を考慮して正確に伝える力のこと。

　＜ポイント＞

　(1)書き手が常識と思って書くべきことを省略しない（具体的な内容を書く）

　(2)伝えたい事を読み手が知りたい事には温度差がある

　(3)文章は方法中心になりがちなので課題や狙いを書く

2.パラレリズムをよくする

　複数の語句を並べるときはすべて同じ形か同じレベルに統一すること。

3.機能表現を知る

　機能表現：○○のために、□□を△△する

　　　　　　↑価値　　　 ↑名詞　↑動詞

4.ドキュメントの本質

　誰に何を伝え、どのような行動を起こしてもらうためなのかを意識して作成する。

5.システム設計表現は5w2h

　why：なぜ（目的・効果）

　　　　効果を明確化し、レビューイが読んでどういうものかがわかり、

　　　　意思決定に役立てるように書く。具体的に何を提供することで、

　　　　具体的にどんなことができるのかを明確にする。

　what：なに（問題・課題）

　　　　あるべき姿と現状が両方わかるように書く。「～だから～の状態にない」

　　　　と目的に結び付くように書く。

　where：どこ（原因）

　how：どのようにして（解決策）

　when：いつ（実現時期）

　who：誰が（実現体制）

　how much：いくらで（必要費用）

6.気をつけたい文章表現

・受動態文章ではなく能動態文章で書く

　「〜することが秘訣といわれています」ではなく「〜することが秘訣です」と書く

・括弧で文章追記はなるべく避ける

・など、等は使わず具体的に書く

・「行う」はなるべく使わない

・5w2hを明確にする

・決まった事と検討課題を明記する

・「思われる」「考えられる」ではなく「〜すべきである」と書く

・具体的な数値を挙げる

7.標準化はムダとりの後にする

・システム開発における10のムダ

(1)要員の空き

(2)情報の停滞

　・議事録の共有が遅いなど頭の中に停滞させない

(3)思考の中断

(4)何のためにどんなものを作成するか不明確なまま作成する資料

(5)準備なしの会議

　・対策案を3つ作成する

　・意思決定社に事前相談

　・出席者への事前連絡（議題や資料は前日の朝を目処に送付しておく）

(6)捜す

　フォルダによる整理をする

(7)転記

(8)管理

(9)加工

　「○○は必須入力とする」ではなく表形式にして必須入力項目に○を入力する

　など工夫する

(10)不良を作ること

　不良を作ると良品と不良品を仕分ける作業を生み障害はさらにムダな作業を生む）

8.設計書に何を書くのか

・プログラムの位置づけ・前提

・プログラムが動く目的と前提条件

・プログラムの動き（IPO）

　・入力

　　画面：レイアウト、動き、入力チェック内容、エラーメッセージ

　　DB：レイアウトと属性

　・処理

　　画面：データの検索方法、画面遷移、画面レイアウト、

　　　　　画面に表示する項目の説明、データの編集方法

　　DB：データの抽出条件、検索方法、編集方法

　・出力

　　画面：動き、出力項目

　　帳票：レイアウト、出力項目、表示順序

　　DB：項目編集要領

・必要に応じてテーブルとそれをアサインしているPGを纏めた資料もあるとよい

9.設計書に適した表現はマトリクス表（抜け・漏れがないことが重要だから）

10.要件定義は「魔法の6マス」が埋まるように進める