ソフトウェアドキュメント

ソフトウェア ドキュメントは、コンピュータソフトウェアに付属するか、ソース コードに埋め込まれるテキストまたは図解です。ドキュメントはソフトウェアの動作方法または使用方法を説明するもので、役割の異なる人々にとって意味が異なる場合があります。

ドキュメントはソフトウェア エンジニアリングの重要な部分です。ドキュメントの種類には次のものがあります。

• 要件– システムの属性、機能、特性、または品質を識別するステートメント。これは、実装される内容または実装済みの内容の基礎となります。
• アーキテクチャ/設計 – ソフトウェアの概要。ソフトウェア コンポーネントの設計に使用される環境との関係と構築原則が含まれます。
• 技術 – コード、アルゴリズム、インターフェース、APIのドキュメント。
• エンドユーザー– エンドユーザー、システム管理者、サポートスタッフ向けのマニュアル。
• マーケティング – 製品のマーケティング方法と市場需要の分析。

要件ドキュメントは、特定のソフトウェアが何をするか、または何をすべきかを説明したものです。これは、開発全体を通じて、ソフトウェアがどのように機能するか、またはどのように動作することを意図しているかを伝えるために使用されます。また、ソフトウェアが何をするかについての合意または合意の基盤としても使用されます。要件は、エンド ユーザー、顧客、プロジェクト マネージャー、営業、マーケティング、ソフトウェア アーキテクト、ユーザビリティ エンジニア、インタラクション デザイナー、開発者、およびテスターなど、ソフトウェアの作成に関与するすべての人によって作成および使用されます。

要件には、さまざまなスタイル、表記法、形式があります。要件は、目標に近いもの (例:分散作業環境)、設計に近いもの (例:構成ファイルを右クリックして「ビルド」機能を選択するとビルドを開始できる)、およびその中間のあらゆるものになります。要件は、自然言語での記述、描画された図、詳細な数式、またはこれらすべての組み合わせとして 指定できます。

要件ドキュメントの多様性と複雑さは、それを実証済みの課題にしています。要件は暗黙的で、見つけるのが難しい場合があります。必要なドキュメントの量と種類、アーキテクチャと設計のドキュメントに残せる量を正確に把握することは困難であり、ドキュメントを読んで使用するさまざまな人々を考慮して要件をドキュメント化する方法を把握することは困難です。したがって、要件ドキュメントは不完全であることが多いです（または存在しません）。適切な要件ドキュメントがないと、ソフトウェアの変更はより困難になり、エラーが発生しやすくなり（ソフトウェアの品質が低下します）、時間がかかります（コストがかかります）。

要件ドキュメントの必要性は、通常、製品の複雑さ、製品の影響、およびソフトウェアの寿命に関連しています。ソフトウェアが非常に複雑であったり、多くの人によって開発されていたりする場合 (携帯電話ソフトウェアなど)、要件は達成すべきことをより適切に伝えるのに役立ちます。ソフトウェアが安全性が重要で、人命に悪影響を与える可能性がある場合 (原子力システム、医療機器、機械設備など)、より正式な要件ドキュメントが必要になることがよくあります。ソフトウェアの寿命が 1 ～ 2 か月と予想される場合 (特定のキャンペーン専用に開発された非常に小さな携帯電話アプリケーションなど)、要件ドキュメントはほとんど必要ない可能性があります。ソフトウェアが最初のリリースであり、後でその上に構築される場合、要件ドキュメントは、ソフトウェアの変更を管理し、ソフトウェアが変更されたときにソフトウェアに何も壊れていないことを確認するときに非常に役立ちます。

従来、要件は要件ドキュメントで指定されます (たとえば、ワード プロセッサ アプリケーションやスプレッドシート アプリケーションを使用)。要件ドキュメント (および一般的なソフトウェア ドキュメント) の複雑さと変化の増大を管理するために、データベース中心のシステムと専用の要件管理ツールが推奨されています。

アジャイル ソフトウェア開発では、要件は多くの場合、受け入れ基準を伴うユーザー ストーリーとして表現されます。ユーザー ストーリーは通常、機能またはエピックの一部であり、ビジネス要件に基づいてユーザーに特定の価値を提供する、より広範な機能または関連する機能のセットです。

アーキテクチャ ドキュメント (ソフトウェア アーキテクチャ記述とも呼ばれる) は、特殊なタイプの設計ドキュメントです。ある意味では、アーキテクチャ ドキュメントはコードから派生した 3 番目のドキュメントです (設計ドキュメントが 2 番目のドキュメント、コード ドキュメントが 1 番目のドキュメント)。アーキテクチャ ドキュメントには、コード自体に固有のものはほとんどありません。これらのドキュメントでは、特定のルーチンをプログラムする方法や、その特定のルーチンが現在の形式で存在する理由について説明しておらず、代わりに、そのようなルーチンが存在する理由となる一般的な要件を単に示しています。優れたアーキテクチャ ドキュメントは、詳細が少なく、説明が充実しています。低レベルの設計に対するアプローチを提案することはあっても、実際の調査トレード スタディは他のドキュメントに任せます。

もう 1 つのタイプの設計ドキュメントは、比較ドキュメント、またはトレード スタディです。これは、多くの場合、ホワイト ペーパーの形をとります。システムの特定の側面に焦点を当て、代替アプローチを提案します。ユーザー インターフェイス、コード、設計、さらにはアーキテクチャ レベルの場合もあります。状況の概要を示し、1 つ以上の代替案を説明し、それぞれの長所と短所を列挙します。優れたトレード スタディ ドキュメントは、調査を重視し、アイデアを明確に表現し (読者を惑わすために難解な専門用語に大きく依存することなく)、最も重要なのは公平であることです。最善と思われるソリューションのコストについて、正直かつ明確に説明する必要があります。トレード スタディの目的は、特定の観点を押し付けるのではなく、最善のソリューションを考案することです。結論を述べないこと、またはどの代替案もベースラインよりも十分に優れているわけではないと結論付けてもまったく問題ありません。これは、マーケティング手法としてではなく、科学的な取り組みとして取り組む必要があります。

エンタープライズ ソフトウェア開発における設計ドキュメントの非常に重要な部分は、データベース設計ドキュメント (DDD) です。これには、概念的、論理的、および物理的な設計要素が含まれます。DDD には、データベースを操作するユーザーが必要とする正式な情報が含まれています。DDD を作成する目的は、シーン内のすべてのプレーヤーが使用する共通ソースを作成することです。潜在的なユーザーは次のとおりです。

• データベースデザイナー
• データベース開発者
• データベース管理者
• アプリケーションデザイナー
• アプリケーション開発者

リレーショナル データベースシステムについて説明する場合、ドキュメントには次の部分を含める必要があります。

• エンティティ - リレーションシップ スキーマ(拡張または非拡張) には、次の情報とその明確な定義が含まれます。
  • エンティティ セットとその属性
  • 関係とその属性
  • 各エンティティセットの候補キー
  • 属性とタプルベースの制約
• リレーショナル スキーマには次の情報が含まれます。
  • テーブル、属性、およびそのプロパティ
  • ビュー
  • 主キー、外部キーなどの制約、
  • 参照制約のカーディナリティ
  • 参照制約のカスケーディングポリシー
  • 主キー

シーン内のすべての俳優が使用するすべての情報を含めることが非常に重要です。また、データベースに変更が発生したときにドキュメントを更新することも非常に重要です。

ソースコードに関連付けられたコードドキュメント（ READMEファイルやAPIドキュメントを含む）は、詳細であることは重要ですが、冗長すぎて時間がかかりすぎたり、メンテナンスが困難になったりしないようにする必要があります。APIライターによってドキュメント化されているソフトウェアアプリケーションまたはソフトウェア製品に固有のさまざまなハウツーおよび概要ドキュメントガイドがよく見られます。このドキュメントは、開発者、テスター、およびエンドユーザーが使用できます。今日、多くのハイエンドアプリケーションは、電力、エネルギー、輸送、ネットワーク、航空宇宙、安全性、セキュリティ、産業オートメーション、およびその他のさまざまなドメインの分野で見られます。基本レベルと高度なレベルの情報は、アーキテクチャの変更に伴って時間の経過とともに変化する可能性があるため、このような組織では技術ドキュメントが重要になっています。優れたコードドキュメントの存在は、実際にソフトウェアのメンテナンスコストを削減するという証拠があります。^[1]

コード ドキュメントはリファレンス ガイドスタイルで編成されることが多く、プログラマーが任意の関数またはクラスをすばやく検索できます。

多くの場合、Doxygen、NDoc、Visual Expert、Javadoc、JSDoc、EiffelStudio、Sandcastle、ROBODoc、POD、TwinText 、 Universal Reportなどのツールを使用して、コード ドキュメントを自動生成できます。つまり、ソース コードからコメントやソフトウェア契約(存在する場合) を抽出し、テキスト ファイルやHTMLファイルなどの形式でリファレンス マニュアルを作成します。

ドキュメントを自動生成するというアイデアは、さまざまな理由でプログラマーにとって魅力的です。たとえば、ドキュメントはソースコード自体から抽出されるため（たとえば、コメントを通じて）、プログラマーはコードを参照しながらドキュメントを作成でき、ソースコードの作成に使用したのと同じツールを使用してドキュメントを作成できます。これにより、ドキュメントを最新の状態に保つことがはるかに簡単になります。

考えられる欠点としては、この種のドキュメントを編集できるのはプログラマーだけであり、出力の更新はプログラマーの責任となる (たとえば、ドキュメントを毎晩更新するcron ジョブを実行するなど) という点が挙げられます。これを欠点ではなく利点と考える人もいます。

著名なコンピュータ科学者であるドナルド・クヌースは、ドキュメント作成は後から考えると非常に難しいプロセスになり得ると指摘し、ソースコードと同じ時間と場所で記述され、自動的に抽出される文芸的プログラミングを提唱しています。プログラミング言語のHaskellとCoffeeScriptには、単純な形式の文芸的プログラミングのサポートが組み込まれていますが、このサポートは広く使用されていません。

解明的プログラミングは、実際のプログラミング コンテキストにおける文芸的プログラミングの実践的な適用の結果です。解明的パラダイムでは、ソース コードとドキュメントを別々に保存することを提案しています。

多くの場合、ソフトウェア開発者は、ソース ファイル自体の一部ではない情報を作成し、それにアクセスできる必要があります。このような注釈は通常、コード ウォークや移植など、サードパーティのソース コードを機能的に分析するいくつかのソフトウェア開発アクティビティの一部です。そのため、注釈は、正式なドキュメント システムでは開発の進行が妨げられるソフトウェア開発のどの段階でも、開発者に役立ちます。

コード ドキュメントとは異なり、ユーザー ドキュメントではプログラムの使用方法を簡単に説明します。

ソフトウェア ライブラリの場合、コード ドキュメントとユーザー ドキュメントは実質的に同等であり、結合する価値がある場合もありますが、一般的なアプリケーションではそうならないことがよくあります。

通常、ユーザー ドキュメントではプログラムの各機能について説明し、ユーザーがこれらの機能を理解するのに役立ちます。ユーザー ドキュメントがわかりにくくならないようにし、最新の状態にしておくことが非常に重要です。ユーザー ドキュメントは特定の方法で整理する必要はありませんが、徹底した索引を付けることが非常に重要です。一貫性と簡潔さも非常に重要です。ユーザー ドキュメントは、ソフトウェアの動作を指定する契約書であると見なされます。APIライターは、使用されているソフトウェア アーキテクチャとプログラミング手法をよく理解しているため、優れたユーザー ドキュメントの作成に非常に長けています。テクニカル ライティングも参照してください。

ユーザードキュメントは、さまざまなオンライン形式や印刷形式で作成できます。^[2]ただし、ユーザードキュメントを整理する方法は大きく分けて3つあります。

1. チュートリアル：チュートリアルアプローチは、特定のタスクを達成するための各ステップをガイドするものであり、新しいユーザーにとって最も有用であると考えられています。^[3]
2. テーマ別:テーマ別アプローチでは、章やセクションが特定の関心領域に集中しており、中級ユーザーにとってより一般的に使用されます。著者の中には、ユーザーのニーズを満たすために、知識ベースの記事を通じて自分の考えを伝えることを好む人もいます。このアプローチは、通常、情報技術などのダイナミックな業界で実践されています。^[4]
3. リストまたは参照:最後のタイプの整理原則は、コマンドまたはタスクをアルファベット順にリストするか、相互参照インデックスを使用して論理的にグループ化するものです。この後者のアプローチは、探している情報の種類を正確に把握している上級ユーザーにとってより便利です。

ソフトウェア ドキュメントに関してユーザーの間でよくある不満は、これら 3 つのアプローチのうち 1 つだけが採用され、他の 2 つがほとんど排除されていることです。パーソナル コンピュータ用のソフトウェア ドキュメントは、コマンドやメニュー項目に関する参照情報のみを提供するオンライン ヘルプに限定されるのが一般的です。新しいユーザーを指導したり、経験豊富なユーザーがプログラムを最大限に活用できるように支援したりする仕事は、ソフトウェア開発者から多大な支援を受けることが多い民間の出版社に任されています。

他の技術文書と同様に、優れたユーザードキュメントは組織化された開発プロセスから恩恵を受けます。ユーザードキュメントの場合、業界で一般的に行われるプロセスは5つのステップで構成されます。^[5]

1. ユーザー分析、プロセスの基礎研究段階。^[6]
2. 計画段階、または実際の文書化段階。^[7]
3. 草稿レビューは、前のステップで作成された草稿に対するフィードバックを求める段階です。^[8]
4. ユーザビリティテストでは、文書のユーザビリティを経験的にテストします。^[9]
5. 編集は、ステップ 3 と 4 で収集された情報を使用して最終草稿を作成する最後のステップです。

多くのアプリケーションでは、一般のユーザーが製品についてもっと時間をかけて学習するように促すために、何らかのプロモーション資料が必要です。この形式のドキュメントには、次の 3 つの目的があります。

1. 潜在的なユーザーに製品の魅力を伝え、製品にもっと関わりたいという欲求を植え付けます。
2. 製品が具体的に何をするのかを顧客に知らせ、顧客の期待と実際に受け取る製品が一致するようにします。
3. 他の代替品と比較したこの製品の位置づけを説明します。

「開発者の間でドキュメント作成に対する抵抗があることはよく知られており、強調する必要はない。」^{[10]この状況は、}アジャイルソフトウェア開発 において特に顕著です。なぜなら、これらの方法論では、直接価値をもたらさない不必要な活動を避けようとするからです。具体的には、アジャイル宣言では「包括的なドキュメント作成よりも動作するソフトウェアを重視する」ことを提唱していますが、これは皮肉にも「私たちはコーディングにすべての時間を費やしたいのです。本当のプログラマーはドキュメントを作成しません。」と解釈できます。^[11]

しかし、ソフトウェアエンジニアリングの専門家を対象とした調査では、アジャイル開発においてドキュメンテーションが不要であるとは決して考えられていないことが明らかになりました。しかし、開発にはモチベーションの問題があり、アジャイル開発に合わせたドキュメンテーション方法（評判システムやゲーミフィケーションなど）が必要になる可能性があることは認識されています。^{[12] [13]}

Docs as Code は、ソフトウェア コードと同じ厳密さとプロセスでドキュメントを扱うアプローチです。これには次のものが含まれます。

1. バージョン管理: Git などのシステムを使用して変更を追跡し、バージョンを管理します。
2. 継続的インテグレーション: ドキュメントの生成と更新のプロセスを自動化します。
3. コラボレーション: コード開発と同様に、複数の貢献者が同時にドキュメントに取り組めるようにします。

• 一貫性: ドキュメントをコードベースと同期させ、正確性を確保できます。
• 自動化: 自動化ツールは、フォーマットや展開などの反復的なタスクを処理できます。
• コラボレーション: 開発者、テスター、製品マネージャーなど、さまざまなチーム メンバーからの貢献を奨励します。Docs as Code と Agile 手法を組み合わせることで、高品質で最新のドキュメントを維持するための堅牢なフレームワークが作成されます。この 2 つを統合する方法は次のとおりです。

1. バージョン管理の設定: まず、ドキュメントをバージョン管理システムに配置します。コードベースと同様に構造化します。
2. プロセスの自動化: CI/CD ツールを実装して、ドキュメントの生成と展開を自動化します。
3. 役割を定義する: アジャイル チーム内でドキュメントの役割と責任を割り当てます。全員がドキュメントの重要性を理解していることを確認します。
4. 定期的なレビュー: スプリントの振り返りの一環として、定期的なドキュメントのレビューをスケジュールします。

• API ライター
• ドキュメント生成ツールの比較
• 契約による設計
• 設計文書
• ドキュメント文字列
• ドキュメント
• リテラルプログラミング
• READMEファイル
• ユーザーアシスタンス
• 統一モデリング言語UML