ITエンジニアのための勉強会・イベントレポート情報メディア

苦手を克服!SEのドキュメント作成のコツ
lifehack

苦手を克服!SEのドキュメント作成のコツ

2017.05.23

 
  • このエントリーをはてなブックマークに追加

プログラマからSEに転身した人が特につまずくことが多いのが、ドキュメント作成ではないでしょうか。プログラミングとは違い、文章を分かりやすく書く能力や文章の構成力などが必要になります。そこで今回は、システム開発におけるドキュメント作成のコツをご紹介。面倒なドキュメント作成を、効率よく進められるようにしていきましょう。

河村真里

SEが制作するドキュメントとは

SEは、各開発工程においてさまざまなドキュメントを作成します。まず要件定義工程において要件定義書を作成した後、基本設計(外部設計)工程でシステム構成図や業務フロー図、ER図、テーブル定義書、そしてI/O関連図や画面/帳票レイアウトなどの基本設計書を作成していきます。次に詳細設計(内部設計)工程でプログラムの仕様を詳しく記載した詳細設計書を作成し、開発工程に進みます。続いて試験工程では、単体試験・結合試験・総合試験において、それぞれ試験項目表や報告書、障害管理表などを作成。その後システムの導入に向けて、ユーザーマニュアルなどを作成していきます。
これらは代表的なドキュメントであり、SEはこのほかにも多数のドキュメントを作成しなければなりません。作成時間も限られているので、たくさんのドキュメントを効率よく正確に作成することが大切です。

設計書や試験項目表の場合

開発工程で用いる各種設計書や、試験工程で使用する試験項目表などは、主に開発者向けのドキュメントになります。この資料さえ見ればプログラマや試験実施者が的確に作業できるよう、必要な情報を全て記載しなくてはなりません。作成時間を短縮するためにドキュメントを簡素化したいという人も多いと思いますが、ここで手を抜くと担当者から何度も質問が発生し、結果的に余計に時間がかかってしまいます。
設計書の場合は、入力値の桁数やnullが渡された場合の処理など、コーディングに必要な情報を漏らさず記載するようにしましょう。自分がコーディングをするときに、どんな情報が必要になるのか想像しながら作成すると良いですね。
試験項目表の場合は、テスト環境やテスト実施手順などを具体的に記載し、誰もが正しい方法で試験できるようなドキュメントに仕上げることが大切です。また単体試験の場合は該当プログラムの動きを、結合試験や総合試験の場合はシステム構成や業務フローまでよく理解した上で、全ての検証パターンを網羅した試験項目表を作成しましょう。

要件定義書やユーザーマニュアルの場合

要件定義書やユーザーマニュアルなどは、主にクライアントやユーザー向けのドキュメントになります。そのため、専門用語は使わず誰でも分かる言葉で明確に記載することが大切です。さらに、文章だけではなく図や表、画像などを適宜、活用しながら作成すると良いでしょう。
開発者側だとつい専門用語を使ってしまったり、説明を省いてしまったりすることが多いので、丁寧すぎるくらいの文章を意識してみてください。難しい言葉には注釈を付けたり、操作手順は実際の画面画像と共に記載したりすると良いですね。また、IT知識のない新入社員に作成したドキュメントを読んでもらい、理解できるか確認してみるのもおすすめです。

まとめ

システム開発におけるドキュメント作成のコツをご紹介してきましたが、いかがでしたか? SEが作成しなければならないドキュメントはかなり多いですが、コツさえ掴めばかなり楽に、そして素早く作業できるようになります。SEにとってドキュメント作成能力は必須ですので、ぜひ早めにスキルを磨いておきましょう。

原稿: 河村真里
SEとして勤務後、ライターに転身。何でも手を出したくなる雑食系。
IT関連情報のほか、旅行、グルメ、インテリアなど幅広いジャンルを執筆しています。

苦手を克服!SEのドキュメント作成のコツ

この記事はどうでしたか?

おすすめの記事

キャリアを考える

BACK TO TOP ∧

FOLLOW