導入
ソフトウェア ドキュメントは、コンピュータ ソフトウェアに付属する文書です。ソフトウェアの仕組みや使用方法について説明します。この用語は、プロフィールが異なる人にとっては異なる意味を持ちます。
ドキュメントはソフトウェアエンジニアリングの重要な部分ですが、見落とされがちです。
文書の種類
ドキュメントにはいくつかの種類があります。
- 必要性の表現 (記入または英語版に翻訳)。
- アーキテクチャ/デザイン–ソフトウェアの概要。これには、環境との関係や、ソフトウェア コンポーネントの設計と作成に使用される原則が含まれます。
- 技術 – コード、アルゴリズム、インターフェイス、プログラミングインターフェイス (API) のドキュメント。
- ユーザー – ユーザー、システム管理者、サポート担当者向けのマニュアル。
- マーケティング– 製品の説明書とプロモーション保証。
必要性の表現
アーキテクチャと設計のドキュメント
アーキテクチャ文書は特別なタイプの設計文書です。ある意味、アーキテクチャ ドキュメントはコードの 3 次派生物です (設計ドキュメントは 2 次派生で、コード ドキュメントは 1 番目の派生です)。アーキテクチャ文書には、コード自体に固有のものはほとんどありません。これらの文書では、特定の関数 (ルーチン) をプログラムする方法や、その特定の関数がなぜその形式で存在するのかについては説明されていませんが、そのような関数の存在を動機付ける一般的な要件の概要が説明されています。優れたアーキテクチャ文書には、詳細は省略されていますが、説明は豊富に含まれています。下位レベルの設計に対するアプローチを提案することはできますが、実際の探索的研究は他の論文に委ねられます。
もう 1 つのタイプの設計ドキュメントは比較ドキュメントです。これは多くの場合、ホワイト ペーパーの形式になります。システムの特定の側面に焦点を当て、代替アプローチを提案します。これは、ユーザーインターフェイスレベル、コード レベル、設計レベル、さらにはアーキテクチャ レベルにまで及ぶ可能性があります。 「IS」（情報システム）の状況に焦点を当て、利点と欠点を示して 1 つ以上の代替案を説明します。優れた比較研究は、調査に重点を置き、そのアイデアを明確に表現しており（読者の目をくらませるような難解な専門用語に過度に依存することなく）、そして何よりも公平です。彼は、どのようなソリューションであっても、それがもたらす最善の効果に関連して、そのコストを正直かつ明確に説明しなければなりません。比較研究の目的は、特定の観点を押し付けることではなく、最適な解決策を見極めることです。結論を出さないこと、または変更を正当化するために現在の状況よりも大きな利点をもたらさない選択肢がないと結論付けることは、まったく問題ありません。これはマーケティング手法としてではなく、科学的な取り組みとして考えられる必要があります。
技術文書
技術文書に関しては、いくつかの種類の文書を区別する必要があります。
- オペレーティング ソフトウェアに関連するドキュメント。オペレーターにコンピューター ハードウェア(コンピューター) の使用方法を説明します。
- アプリケーション ソフトウェア (会社の主要な機能: 財務、購買、物流など) に関連し、ソフトウェアの使用方法を示す文書。
ほとんどのプログラマーは、アプリケーション ソフトウェアのドキュメントを指すときに「 ソフトウェア ドキュメント」という用語を使用します。ソフトウェアを開発する場合、ソースコードだけでは不十分です。予想される操作のさまざまな側面を説明するテキストが添付されている必要があります。このドキュメントは通常、ソース コード自体に含まれているため、ソース コードを通過する可能性がある人は誰でも簡単にアクセスできます。
この文書は高度に技術的なものになる可能性があり、主にプログラミング インターフェイス (API)、データ構造、およびアルゴリズムを定義および説明するために使用されます。たとえば、このドキュメントを使用して、変数m_name が人の姓名を参照していることを説明できます。コードドキュメントは正確であることが重要ですが、保守が困難になるほど冗長でないことも重要です。
多くの場合、 Doxygenや javadoc などのツールやドキュメント ジェネレーターを使用して、コード ドキュメントを自動的に生成できます。ソース コードから解説を抽出し、テキストや HTML ファイルなどの形式でリファレンス マニュアルを作成します。コード ドキュメントは多くの場合、リファレンス ガイドのスタイルで編成されており、プログラマは関数やクラスをすぐに見つけることができます。
実際、多くのプログラマーは、さまざまな理由からドキュメントを自動的に生成するというアイデアを好みます。たとえば、ソース コード自体から（コメントなどを通じて）抽出されるため、プログラマはコードを参照してコードを作成でき、ソース コードの開発に使用したのと同じツールを使用してドキュメントを作成できます。これにより、ドキュメントの更新がはるかに簡単になります。
もちろん、欠点は、この種のドキュメントを編集できるのはプログラマだけであり、出力を更新するかどうかはプログラマ次第であることです (たとえば、夜間にcrontab を実行してドキュメントを更新するなど)。これをデメリットではなくメリットとして捉える人もいるかもしれません。
Donald Knuth 氏は、ドキュメンテーションは後から考えるのが非常に難しいプロセスになる可能性があると主張し、ソース コードと同じ時間と場所でドキュメンテーションを作成し、自動的な手段で抽出することを含む、読み書き可能なプログラミングを推奨しました。
ユーザードキュメント
コードのドキュメントとは異なり、ユーザー ドキュメントは通常、プログラムのソース コードから完全に削除され、単にその使用方法を説明するだけです。
ソフトウェア ライブラリの場合、コード ドキュメントとユーザー ドキュメントは実際に結合することができ、それらをグループ化する価値がありますが、これは一般的なアプリケーションでは必ずしも有効であるとは限りません。
Lisp マシンは、すべてのコード部分にドキュメントフィールドが付属するという伝統に従いました。強力な検索機能 (Unix に同化された適切なコマンドに基づく) およびオンライン ソースに関連して、 Lispユーザーはドキュメントを参照し、関連する機能を独自のコードで直接実行できます。このレベルの容易さは、おそらくより近代的なシステムでは知られていません。
通常、ユーザー ドキュメントには、プログラムの各機能と、それを呼び出すために必要なさまざまな手順が説明されています。優れたユーザー ドキュメントは、徹底したオンライン サポートを提供することにもつながります。ユーザー文書が混同されず、最新のものであることが非常に重要です。ユーザードキュメントは特定の方法で構造化する必要はありませんが、正確なインデックスがあることが非常に重要です。一貫性とシンプルさも、非常に貴重な 2 つの特質です。ユーザードキュメントは、ソフトウェアが何をすべきかを指定する契約とみなされます。テクニカルライティングも参照してください。
ユーザードキュメントを整理するには主に 3 つの方法があります。
- チュートリアル
- 私たちは、チュートリアルのアプローチが新しいユーザーにとって最も役立つと考えています。この方法では、ユーザーは特定のタスクを完了するための各ステップをガイドされます。
- テーマ別
- 中級ユーザーの場合は、章やセクションが特定の関心領域に焦点を当てるテーマ別アプローチが一般的に採用されます。
- リスト
- 最後のタイプの編成原則は、コマンドまたはタスクを単純にアルファベット順にリストするもので、多くの場合は下付き文字を使用します。この後者のアプローチは、探している情報の種類を正確に知っている上級ユーザーにとって非常に興味深いものです。ソフトウェアのドキュメントに関してユーザーが広く表明している不満は、これら 3 つのアプローチのうち 1 つだけが採用され、他の 2 つは除外されていることです。
マイクロコンピュータの場合、ソフトウェア マニュアルの提供はオンライン ヘルプに限定されるのが一般的で、コマンドやメニュー行に関する参照情報に限定されます。新しいユーザーを指導したり、経験豊富なユーザーがプログラムを最大限に活用できるように支援したりする作業は民間の発行者に任されており、ソフトウェア開発者はそれに多大な支援を提供しています。
マーケティング資料
多くの用途では、何気なく観察する人が製品に興味を持ってより多くの時間を費やせるよう、宣伝用の資料が必要です。
この形式のドキュメントには次の 3 つの目的があります。
- 潜在的なユーザーが製品に興味を持つように促し、製品にもっと関わりたいという欲求を植え付けます。
- ユーザーの期待がユーザーが受け取るものと一致するように、製品が正確に何をするのかをユーザーに知らせます。
- 他の代替品と比較したこの製品の位置付けを説明します。
優れたマーケティング手法は、伝えたい点を説明する明確で記憶に残るキャッチフレーズを提供し、またプログラムと他の製品との相互運用性を強調することです。