ITエンジニアの仕事はプログラムを書くだけではありません。
要件定義書、外部仕様書、内部設計書、テスト計画書、、、、など作るドキュメントは多岐に渡ります。
むしろ、このようなドキュメントを作るのがITエンジニアの本業のように思えてくることもあります。
プログラマであっても「詳細設計書」「作業報告書」「単体テスト品質見解」くらいは書きます。
驚くほどにドキュメントを書くのが下手な人がいます。そういう人に向けて、ドキュメントを書くための最低限の作法を書いていきます。
- 長い文を書かない
- 主語を書く
- 表にする
これだけは知っておくべき国語の作法
イト屋です。
ITエンジニアの仕事の大部分を占めるのが様々なドキュメントを作ることです。
要件定義書、外部仕様書、内部設計書、テスト計画書、、、、、と盛りだくさんです。
本当に文章の勉強をするなら、Webライターになって訓練とか小説を書くなどありますが、そういうレベルに行く前の話をします。
以下のことについて論じます。
- 長いを書かない
- 主語を書く
- 表にする
長い文を書かない
まず、長い文章を書いてはいけません。
以下のような文章があるとしましょう。
東京は人口が1200万人であり人口が密集しており、上場企業の約半分が本社をおき経済の中心と言う事ができ、大学の数が多く教育の中心でもあり、政府、国会があるため政治の中心です。
仕様書でなければあってもおかしくない文章かもしれません。
しかし、仕様書に書く文章としては失格です。1文章、1主張が基本です。
東京は人口が1200万であり人口が密集している。 上場企業の約半分が本社をおき経済の中心である。 大学の数が多く教育の中心である。 政府、国会があるため政治の中心である。
主語を書く
日本語は英語とは異なり文に主語がなくても、文章として成り立ちます。
日本人として暮らしているので、気を抜くと主語のない文章を書いてしまうかもしれません。
ポイントとしては、必ず主語を書くということを心がけてください。
先ほどの文章を再掲します。意味が分かりますが2文目以降主語がありません。
東京は人口が1200万であり人口が密集している。 上場企業の約半分が本社をおき経済の中心である。 大学の数が多く教育の中心である。 政府、国会があるため政治の中心である。
主語をつけてみましょう。
東京は人口が1200万であり人口が密集している。 東京は上場企業の約半分が本社をおき経済の中心である。 東京は大学の数が多く教育の中心である。 東京は政府、国会があるため政治の中心である。
日本人であれば、上記の文章は冗長に感じるのは自然です。しかし、仕様書では冗長さを除くという行為は不要です。
主語がなくて意味が通らないことの方が問題を引き起こす原因となりえますので、くれぐれも、必ず主語を書くようにしましょう。
表にする
冗長な文章を書きだしたと思ったら表にしましょう。つらつらと文章を並べ始めたと感じたら表です。
| # | 都市 | 性質 | 根拠 |
| 1 | 東京 | 人口密集 | 人口が1200万 |
| 2 | 東京 | 経済の中心 | 上場企業の半分が本社を置く |
| 3 | 東京 | 教育の中心 | 大学の数が多い |
| 4 | 東京 | 政治の中心 | 政府、国会がある |
仕様書に書かれたことはテスト工程でテストしなければなりません。
文章で書かれたものと表で書かれたものでは、テストに落とすときの労力が違います。
書いているときは文章でも表でも同じと感じるかもしれませんが、テストを作るときには表で書かれている方がずっと楽に感じます。
ぜひ、表を書いていきましょう。
おまけ：図にする
ここまでで最低限の文章術です。ぜひ実践してください。
仕様書ではさらに図を作るという技法があります。
機能の動きや外部との関わりを説明するときは、表より図の方がよいです。
UMLのシーケンス図などを用いてください。
UMLの使い方は他の機会に記事にしようと思います。
まずは、短い文、主語を書く、表にする、を頭に入れて仕様書を書いていきましょう。
まとめ
ITエンジニアがドキュメントを書くための最低限の3つの作法を説明した。
短い文、主語を書く、表にするを覚えておきましょう。
コメント