プログラムのドキュメントの書き方
プログラムのドキュメントの書き方
2021年7月21日
プログラムのドキュメントの書き方
プログラミングを仕事として行う場合、プログラミングのドキュメントは必須の物の一つです。趣味でプログラムを作るのとは違って、いろいろな人が作成するプログラムに関わってきます。作成するプログラムがどんな物なのかをプログラムを作った人以外の人が理解するのにドキュメントは重要です。
どんなドキュメントが必要か？
会社などでプログラムを開発する場合、沢山のドキュメントが作成されます。 基本的に、割り当てられた仕事毎に幾つか必要なドキュメントがあります。
殆どの仕事には、「入力（インプット）」と「出力（アウトプット）」があります。 その仕事を進めるために必要な情報が「入力（インプット）」で、仕事の結果（成果）が「出力（アウトプット）」になります。プログラムを作る場合の入力は、「どんな機能が必要か」が入力（インプット）になります。この入力の情報に基づいて「どんなプログラム」を作るかが、プログラムを設計する人の出力（アウトプット）になります。
多くの場合、仕事と仕事を繋げる役割をするのが、ドキュメントになります。
従って、一つのプログラムの開発プロジェクトの場合でも、沢山のドキュメントが必要になります。
- 利用者の要望、意見、フィードバックをまとめたもの
- 実際のプログラムの要求をまとめた物
- 実際のプログラムで実現する機能や方法（やり方）をまとめたもの
- プログラムの使い方をまとめた物
- プログラムのテストの方針をまとめた物（テストプラン）
- プログラムのテスト結果をまとめた物（テストレポート）
など基本的なものだけでも結構な数になります。
当然ですが、作成するドキュメントによって書き方も内容も大きく変わってきます。 この記事では、プログラムを作る人が作成するドキュメントで特に大切な「プログラムの使い方」をまとめたドキュメントに絞って考えてみます。
会社などでプログラムを開発する場合、沢山のドキュメントが作成されます。 基本的に、割り当てられた仕事毎に幾つか必要なドキュメントがあります。
殆どの仕事には、「入力（インプット）」と「出力（アウトプット）」があります。 その仕事を進めるために必要な情報が「入力（インプット）」で、仕事の結果（成果）が「出力（アウトプット）」になります。プログラムを作る場合の入力は、「どんな機能が必要か」が入力（インプット）になります。この入力の情報に基づいて「どんなプログラム」を作るかが、プログラムを設計する人の出力（アウトプット）になります。
多くの場合、仕事と仕事を繋げる役割をするのが、ドキュメントになります。
従って、一つのプログラムの開発プロジェクトの場合でも、沢山のドキュメントが必要になります。
- 利用者の要望、意見、フィードバックをまとめたもの
- 実際のプログラムの要求をまとめた物
- 実際のプログラムで実現する機能や方法（やり方）をまとめたもの
- プログラムの使い方をまとめた物
- プログラムのテストの方針をまとめた物（テストプラン）
- プログラムのテスト結果をまとめた物（テストレポート）
など基本的なものだけでも結構な数になります。
当然ですが、作成するドキュメントによって書き方も内容も大きく変わってきます。 この記事では、プログラムを作る人が作成するドキュメントで特に大切な「プログラムの使い方」をまとめたドキュメントに絞って考えてみます。
誰が使うドキュメントか？
プログラムの使い方をまとめたドキュメント作成する場合に一番最初に確認することがあります。 それは、「誰がそのドキュメントを見る（読む）のか」です。
当然、プログラムの場合は、「利用者」という事になります。しかし、その利用者はどんな人かイメージできますか？ まずは、ここが第一関門です。
実は、こうしたプログラムの取り扱いをまとめたドキュメントの利用者は大きく分けて二つのグループに分けることができます。
- プログラムの知識が殆どない一般の利用者
- プログラムの開発関係者
プログラムの使い方のドキュメント、すなわち「取扱説明書」のようなドキュメントなので、利用する人はプログラムを使うだけと思いがちですが、実はプログラムの開発関係者が中心に使う場合も結構あります。
例えば、Web アプリ（Web サービス）を例に考えてみます。
多くの、Web アプリや Web サービスは、Web ブラウザで動作するフロントエンドと呼ばれる部分と、Web サーバー側で動作するバックエンドのプログラムで構成されるケースが沢山あります。
Web ブラウザで動作するフロントエンドの部分は、実際の利用者が直接操作する部分ですので、殆どの利用者はプログラミングの知識がない場合が多くなります。一方で、Web サーバー側で動作するバックエンドの場合、利用するのはフロントエンドのプログラムということになるので、基本的にはプログラマが利用者になります。一般の利用者には見えない部分だからです。
Web アプリの場合は、実際は直感的に操作する場合が多く、取扱説明書がなくても操作できるような設計にするのが普通です。従って、実際に利用者がこのドキュメントを見る機会が殆どないケースも結構あります。しかし、複雑な機能を提供する場合には、ドキュメントがないと利用が難しくなります。いずれにしても、プログラマ以外の人が利用するケースが多いので、内容もプログラミングの専門用語を使わずに操作の方法や手順を中心に記述することになります。
一方で、バックエンドの場合、利用するのはプログラミングの知識がある人が対象になるので、プログラミングをする上で、必要な情報を細かく記述する必要があって、専門性が高い内容のドキュメントになります。
このように、ドキュメントを利用する人によって必要な内容も変わってきますのでその辺を考慮するために、まずは利用者をきちんと把握してそれに合ったドキュメントの方針を決めることが必要です。
プログラムの使い方をまとめたドキュメント作成する場合に一番最初に確認することがあります。 それは、「誰がそのドキュメントを見る（読む）のか」です。
当然、プログラムの場合は、「利用者」という事になります。しかし、その利用者はどんな人かイメージできますか？ まずは、ここが第一関門です。
実は、こうしたプログラムの取り扱いをまとめたドキュメントの利用者は大きく分けて二つのグループに分けることができます。
- プログラムの知識が殆どない一般の利用者
- プログラムの開発関係者
プログラムの使い方のドキュメント、すなわち「取扱説明書」のようなドキュメントなので、利用する人はプログラムを使うだけと思いがちですが、実はプログラムの開発関係者が中心に使う場合も結構あります。
例えば、Web アプリ（Web サービス）を例に考えてみます。
多くの、Web アプリや Web サービスは、Web ブラウザで動作するフロントエンドと呼ばれる部分と、Web サーバー側で動作するバックエンドのプログラムで構成されるケースが沢山あります。
Web ブラウザで動作するフロントエンドの部分は、実際の利用者が直接操作する部分ですので、殆どの利用者はプログラミングの知識がない場合が多くなります。一方で、Web サーバー側で動作するバックエンドの場合、利用するのはフロントエンドのプログラムということになるので、基本的にはプログラマが利用者になります。一般の利用者には見えない部分だからです。
Web アプリの場合は、実際は直感的に操作する場合が多く、取扱説明書がなくても操作できるような設計にするのが普通です。従って、実際に利用者がこのドキュメントを見る機会が殆どないケースも結構あります。しかし、複雑な機能を提供する場合には、ドキュメントがないと利用が難しくなります。いずれにしても、プログラマ以外の人が利用するケースが多いので、内容もプログラミングの専門用語を使わずに操作の方法や手順を中心に記述することになります。
一方で、バックエンドの場合、利用するのはプログラミングの知識がある人が対象になるので、プログラミングをする上で、必要な情報を細かく記述する必要があって、専門性が高い内容のドキュメントになります。
このように、ドキュメントを利用する人によって必要な内容も変わってきますのでその辺を考慮するために、まずは利用者をきちんと把握してそれに合ったドキュメントの方針を決めることが必要です。
取り扱いに必要なのは「手順」と「必要な物（事）」
この記事で取り上げているドキュメントの種類は「取り扱い」です。 それに必要な要素は、「手順」と「必要な物（事）」
- 手順は操作の順番です
- 必要な物（事）は操作する上の「前提条件」です
手順はわかりやすいですよね、やることを細かいステップの分けてその順番を詳しく書くだけです。
意外に難しいのが、必要な物（事）です。前提条件と言い換えていますが、「やる事」をする上で必要になる物や操作をきちんと書いて置きます。
例えば、ある特定の順番で操作しなければ行けない事や、操作する前に入力したり、ファイルを選択しなければ行けない事など、操作の前提になる準備や操作をきちんと明示するする事が大切です。
簡単なプログラムの場合は、あまり組み合わせや、条件がないので比較的簡単ですが、少しプログラムが複雑になってくると書くことが多くなります。
例えば、お絵かきソフトで描いた線を消す操作を考えてみてください。
- 消したい線を選択する
- 消去ボタンを押す
- 消去の確認をする
のようなステップで消去するように書きます。 この際、消したい線を選択していない場合に、「２」の消去ボタンの操作を行った場合はどうなるでしょうか？ そのような、ケースが存在する場合は、そのこともドキュメントに書いておくのが親切です。
あるいは、そのような操作ができないようにプログラムを作ることも可能です。
プログラムを作成する人がこのようなドキュメントを各意味はこのあたりにあります。
実は、操作を詳しく書いていると、こうしたケースに度々遭遇するのは普通です。この場合、こうした意図しない操作をできないようにプログラムを書いてしまえば、ドキュメントで説明する手間がかなり省けます。また、いろいろなケースの詳細を予め考慮することで、プログラムの不具合も大幅に減らすことが可能になります。
この記事で取り上げているドキュメントの種類は「取り扱い」です。 それに必要な要素は、「手順」と「必要な物（事）」
- 手順は操作の順番です
- 必要な物（事）は操作する上の「前提条件」です
手順はわかりやすいですよね、やることを細かいステップの分けてその順番を詳しく書くだけです。
意外に難しいのが、必要な物（事）です。前提条件と言い換えていますが、「やる事」をする上で必要になる物や操作をきちんと書いて置きます。
例えば、ある特定の順番で操作しなければ行けない事や、操作する前に入力したり、ファイルを選択しなければ行けない事など、操作の前提になる準備や操作をきちんと明示するする事が大切です。
簡単なプログラムの場合は、あまり組み合わせや、条件がないので比較的簡単ですが、少しプログラムが複雑になってくると書くことが多くなります。
例えば、お絵かきソフトで描いた線を消す操作を考えてみてください。
- 消したい線を選択する
- 消去ボタンを押す
- 消去の確認をする
のようなステップで消去するように書きます。 この際、消したい線を選択していない場合に、「２」の消去ボタンの操作を行った場合はどうなるでしょうか？ そのような、ケースが存在する場合は、そのこともドキュメントに書いておくのが親切です。
あるいは、そのような操作ができないようにプログラムを作ることも可能です。
プログラムを作成する人がこのようなドキュメントを各意味はこのあたりにあります。
実は、操作を詳しく書いていると、こうしたケースに度々遭遇するのは普通です。この場合、こうした意図しない操作をできないようにプログラムを書いてしまえば、ドキュメントで説明する手間がかなり省けます。また、いろいろなケースの詳細を予め考慮することで、プログラムの不具合も大幅に減らすことが可能になります。
テストも簡単に！
実は、このドキュメントをきちんと作成するとプログラムのテストも簡単になります。 既に紹介していますが、プログラムを作成した場合、基本機能の動作確認は必須です。
プログラムのコーディングが終了して、テストを開始する場合、こうした取り扱いのドキュメントやテストプランがないと、行き当たりばったりで操作をしてテストする事になります。何か不具合を見つけてプログラムを修正した場合は、また同じテストを繰り返す必要があります。テストの手順が決まっていないと、テストの抜けも起きやすくなりますし、テストの効率も悪くなります。
操作説明のドキュメントがあれば、テストプランが仮に用意されていなくても、ドキュメントで書かれた手順を実行すれば良いのでテストでやることも、抜けも最小限にする事ができます。 時間に余裕があれば、ドキュメントに書かれた手順や前提条件以外の操作を確認すれば、一通りのテストが可能になります。 あとは、操作結果を残せるようなシートを用意しておけば、取り扱い説明のドキュメントとテストプランは同じドキュメントでカバーが可能です。フリーランスの場合は、個別にドキュメントを作成するのは大変ですが、取り扱いの説明とテストプランを兼ねるような形でドキュメントを準備すれば、作成の手間も省けます。
ここで大切なのは、このドキュメントをできれば、プログラムのコーディングを開始する前に作ると、さらに効率がアップします。 想定する操作を記述することで、いかに予期しない操作を避けるようにプログラムを書く方針が予めわかるからです。 慣れないと、プログラム作成前にこうしたドキュメントを作るのは少し難しいと思いますが、まずは「できる限り」想像してドキュメントを作るようにすると、次第に慣れてきて、プログラムを書かなくても、操作がイメージできるようになります。
これは、プログラムの作り方をプログラムを書きながら考えるのではなくて、予め作り方を考えてからコーディングする事になるので、完成したプログラムの品質は大幅に高くなります。
実は、このドキュメントをきちんと作成するとプログラムのテストも簡単になります。 既に紹介していますが、プログラムを作成した場合、基本機能の動作確認は必須です。
プログラムのコーディングが終了して、テストを開始する場合、こうした取り扱いのドキュメントやテストプランがないと、行き当たりばったりで操作をしてテストする事になります。何か不具合を見つけてプログラムを修正した場合は、また同じテストを繰り返す必要があります。テストの手順が決まっていないと、テストの抜けも起きやすくなりますし、テストの効率も悪くなります。
操作説明のドキュメントがあれば、テストプランが仮に用意されていなくても、ドキュメントで書かれた手順を実行すれば良いのでテストでやることも、抜けも最小限にする事ができます。 時間に余裕があれば、ドキュメントに書かれた手順や前提条件以外の操作を確認すれば、一通りのテストが可能になります。 あとは、操作結果を残せるようなシートを用意しておけば、取り扱い説明のドキュメントとテストプランは同じドキュメントでカバーが可能です。フリーランスの場合は、個別にドキュメントを作成するのは大変ですが、取り扱いの説明とテストプランを兼ねるような形でドキュメントを準備すれば、作成の手間も省けます。
ここで大切なのは、このドキュメントをできれば、プログラムのコーディングを開始する前に作ると、さらに効率がアップします。 想定する操作を記述することで、いかに予期しない操作を避けるようにプログラムを書く方針が予めわかるからです。 慣れないと、プログラム作成前にこうしたドキュメントを作るのは少し難しいと思いますが、まずは「できる限り」想像してドキュメントを作るようにすると、次第に慣れてきて、プログラムを書かなくても、操作がイメージできるようになります。
これは、プログラムの作り方をプログラムを書きながら考えるのではなくて、予め作り方を考えてからコーディングする事になるので、完成したプログラムの品質は大幅に高くなります。
まとめ
プログラムの取り扱いのドキュメントの基本は「手順」と「前提条件」です。
これらをプログラムを作成する前に書くことで、不必要な操作や意図しない操作をコーディングで避けてドキュメントで書く範囲を最小限にするとともに、プログラムの品質を高めることができます。
ところで、ドキュメントがきちんと存在すると、例えば、プログラムのテストなどを他の人に頼むことも簡単になります。 ここで大切になるのは、プログラムを開発した人以外がわかるようなドキュメントにする事がとても大切です。
プログラムを作った人なら知っている「暗黙の了解」も他の人にはわからない物です。こうした部分をしっかりカバーしたドキュメントにすることで、プログラムの設計、プログラムの検証、利用者の誤操作によるトラブルを最小限に抑えることができます。
プログラムの取り扱いのドキュメントの基本は「手順」と「前提条件」です。
これらをプログラムを作成する前に書くことで、不必要な操作や意図しない操作をコーディングで避けてドキュメントで書く範囲を最小限にするとともに、プログラムの品質を高めることができます。
ところで、ドキュメントがきちんと存在すると、例えば、プログラムのテストなどを他の人に頼むことも簡単になります。 ここで大切になるのは、プログラムを開発した人以外がわかるようなドキュメントにする事がとても大切です。
プログラムを作った人なら知っている「暗黙の了解」も他の人にはわからない物です。こうした部分をしっかりカバーしたドキュメントにすることで、プログラムの設計、プログラムの検証、利用者の誤操作によるトラブルを最小限に抑えることができます。
コメント
コメントを投稿