技術ドキュメントとソフトウェア設計ドキュメント
すでに完成/開発されたクラスライブラリに関するドキュメントを作成しようとしています。
ドキュメントの目的は、このクラスライブラリに含まれているメソッドの種類とその使用方法を理解するために、他の開発者が使用することです。より具体的には、クラスの各メソッドと属性のXMLコメントに基づいて提供するJavadocツールのようなドキュメント。
これまでのところ、ドキュメントの種類について読んでいますが、技術仕様とソフトウェア設計ドキュメントは、そのような情報を提供するものであるようです。
しかし、すでに読んだいくつかの読みに基づいて多くの違いを見ることができないので、それらについて混乱しています。
たとえば ここ 、それはソフトウェア設計ドキュメントがソフトウェアプロジェクトのアーキテクチャにソフトウェア開発チームに全体的なガイダンスを提供するために使用されることを示しています。そして here それはテクニカルドキュメントがソフトウェアプロジェクトに参加する新しい開発者のために使用されることを示していますプロジェクトを紹介するにはどのような情報が役立ちますか？
この観点から、これらのドキュメントは、ソフトウェア開発者がこれまでに開発されたものに慣れることを目的としているようです。しかし、違いは何であり、私の目的にどちらを使用するのですか？
技術文書とは何ですか？
実際の定義：技術文書とは、一部の専門家が必要であるため、一般の人間が理解できない文書を意味します知識。
悪いニュースは、何を入れるかを決定するのに役立たないことです。良い知らせは、これからは自分でこの概念を使って、あなたが理解していないものを修飾することができるということです：「ええと！これらの会計ガイドラインは非常に技術的なドキュメントのようです」君は）。
文書化の目的は何ですか？
本当の質問：テクニカルライティングの場合、他のライティングと同様に、最初の質問は、対象読者が何であり、これの主な目的を知ることですドキュメントは次のとおりです。
- 新しいチームメンバー向けですか？最も重要なことは、概要（例：アーキテクチャーとレイヤー、主要コンポーネント）、高レベルドメインモデル（つまり コンテキストマップ ）、およびいくつかの実践的な情報（例：ディレクトリ構造、ツールセット）を提供することです。使用、命名規則、読むための他の重要なドキュメントへのリンク）。詳細はいずれにしても、説明のないクリーンなコードまたは便利なコメントのコードに含まれます。
- library users用ですか？ javadocまたはdoxygenは、コードに埋め込まれているコメントに基づいて適切なリファレンスドキュメントを生成します（そのため、メンテナンスが簡単です）。残念ながら、この詳細情報では、ライブラリの設計を簡単に理解できません。繰り返しになりますが、ライブラリのアーキテクチャ、およびそのさまざまなコンポーネントがどのように相互に作用し、相互に依存するかについて、高レベルの概要を提供する必要があります。ライブラリが独自に販売されている商用製品である場合、この種類のドキュメントは必須です。
致命的な仮定は、技術的なニーズをカバーする「技術文書」を作成できると考えることです。チーム（内部を知る必要がある）とユーザー（ユースケースとインターフェースを理解する必要がある）が理解する詳細のレベルは、多くの場合非常に異なります。
いくつかのアドバイス
Grady Boochは、著書「Object Oriented Analysis and Design Technique」で目的のソフトウェアドキュメントの内容を公開しています。
- 高レベルのシステムアーキテクチャ
- アーキテクチャの主要な抽象化とメカニズム
- システムの主要な側面の構築時の動作を示すシナリオ
彼はさらに非常に具体的なポイントを作りました：
表記法の図で表すことができますが、プログラミング言語で直接言語表現がないこれらの高レベルの構造を文書化し、開発者に特定の重要なクラスのインターフェースを参照して戦術の詳細を確認することをお勧めします。
文書には2つの基本的な種類があります：ユーザーズガイドと参照文書。
（一部の企業は、概要を別の種類として認識しています。以下を参照してください。）
リファレンスドキュメント製品のパブリックインターフェイス全体を入念にかつ正確に一覧表示します。各スイッチとパラメーターの意味、有効と見なされる入力、各ケースで返される内容など。
- Wordpublicインターフェイスに注意してください。その主な目的は、観測された動作のどの詳細が公式に保証され、信頼できるかを指定することです。 （他のすべては実装の詳細であり、予告なしに変更および中断される可能性があることを省略して述べたり示唆したりします。）
- また、単語「全体」にも注意してください。参照の主なセールスポイントは、完全性です。参照にない場合は、（公式に）存在しません。トピックのリファレンスを読んだ場合、そのトピックに関するすべてを知っていることを確認でき、厄介な驚きはありません。
- したがって、リファレンスは学習教材として使用できますが、その主な使用例はギャップを埋めることです。
設計原則はパブリックインターフェースの構造と編成に直接表れるため、リファレンスドキュメントには、製品のインターフェースの一部と側面、および詳細をリストする前に動作の概要セクションを含めることができます（個々のAPIのエントリでの繰り返しを避けるためだけ） 。
- 繰り返しますが、焦点はパブリックインターフェイスであるため、製品の組織と動作を理解するために重要な、ユーザーに表示される詳細に焦点を当て、そのために重要ではない技術は省略または手動で行うことができます。
A ユーザーズガイド目的は、実際の問題および/またはそのクラスを解決するためにパブリックインターフェイスを使用して製品の作成者がどのように想定するかを示すことです：意図した使用パターン、一般的な一般的な問題および提案されたソリューション（特定のAPIにローカルな問題）むしろ参照エントリに属しているようです）。
ユーザーガイドは意図的に不完全であり、「全体像」と主要なポインタのみを提供し、詳細についてはリファレンスに任せています。
ユーザーガイドにも概要テキストを含めることができますが、ここでの概要の焦点は使用パターンです：何がsupposedの後に何の場所から呼び出されるか等.
- 単語が想定されていることに注意してください。これは推奨事項です：「これが、私たちが推奨される方法です。」何がcan（またはできない）は、完全に参照ドキュメントドメインから呼び出すことができます。
一部の会社、例えばMicrosoft、最高レベルの概要を別の種類のドキュメントに分離します。 MSDNの多くの場所で、「Xについて」、「Xの使用」、および「Xリファレンス」に分割されたXのセクションが表示されます。
ご覧のとおり、ユーザーガイドとリファレンスは互いに補完し合い、さまざまなトピックをカバーし、さまざまな観点から説明しています。ガイドは、長期的にはドキュメントを参照しながら、短期的にはユーザーにとってより有益です。
参照は完全であるため、後者に存在する情報はそこから推測できるという点で、ユーザーガイドよりも「優れています」。ただし、学習曲線が急になります。
OTOHユーザーズガイドは、特にインターフェースが急速に変化する場合、維持するのにはるかにはるかに小さくて負担が少ないです。欠点は、ユーザーがあなたが与えたいくつかの例以外に何をしようとしているのかがわからない、どこでどのような構文が許可されているのかなど、ユーザーが確信できないことです。
manページは、リファレンスドキュメントの典型的な例です。一部のmanページの作成者（例：rsync）は、ユーザーのガイドセクションを追加しようとしました-そのため、必要な参照資料を見つけるのが困難になりました。