Loading article…
ソフトウェアドキュメントとは、コンピュータソフトウェアに付属する、またはソースコードに組み込まれた文書や図解のことです。ドキュメントは、ソフトウェアの動作原理や使用方法を説明するものであり、役割の異なる人々にとっては異なる意味を持つ場合があります。
ドキュメント作成はソフトウェアエンジニアリングの重要な要素です。ドキュメントの種類には以下のようなものがあります。
要件定義書とは、特定のソフトウェアが何を行うか、あるいは何を行うべきかを記述したものです。開発全体を通して、ソフトウェアの機能や動作意図を伝えるために使用されます。また、ソフトウェアの動作に関する合意、あるいは合意の基盤としても使用されます。要件定義書は、エンドユーザー、顧客、プロジェクトマネージャー、営業担当者、マーケティング担当者、ソフトウェアアーキテクト、ユーザビリティエンジニア、インタラクションデザイナー、開発者、テスターなど、ソフトウェア開発に関わるすべての人によって作成され、利用されます。
要件は、さまざまなスタイル、表記法、形式性で表現されます。要件は、目標指向的なもの（例：分散型作業環境）、設計に近いもの（例：構成ファイルを右クリックして「ビルド」機能を選択することでビルドを開始できる）、そしてその中間的なものまで多岐にわたります。要件は、自然言語による記述、図、詳細な数式、あるいはそれらの組み合わせとして指定できます。
要件文書の多様性と複雑さゆえに、要件文書の作成は大きな課題となっています。要件は暗黙的で、見つけ出すのが難しい場合があります。必要な文書の量や種類、アーキテクチャや設計文書にどれだけ任せられるかを正確に把握することは困難であり、また、文書を読み利用する様々な人々を考慮して要件をどのように文書化すべきかも難しい問題です。そのため、要件文書は不完全（あるいは存在しない）な場合が少なくありません。適切な要件文書がなければ、ソフトウェアの変更はより困難になり、結果としてエラーが発生しやすくなり（ソフトウェア品質の低下）、時間とコストも増大します。
要件定義書の必要性は、一般的に製品の複雑さ、製品の影響、およびソフトウェアの耐用年数に関連しています。ソフトウェアが非常に複雑であったり、多くの人が開発に関わっている場合（例：携帯電話ソフトウェア）、要件定義書は達成すべき目標をより明確に伝えるのに役立ちます。ソフトウェアが安全性が極めて重要であり、人命に悪影響を及ぼす可能性がある場合（例：原子力発電システム、医療機器、機械設備）、より正式な要件定義書が必要となることがよくあります。ソフトウェアの耐用年数がわずか1～2ヶ月と想定される場合（例：特定のキャンペーン向けに開発された非常に小規模な携帯電話アプリケーション）、要件定義書はほとんど必要ないかもしれません。ソフトウェアが最初のリリースであり、その後改良が加えられる場合、要件定義書はソフトウェアの変更管理や、変更時にソフトウェアに不具合が生じていないことを検証する際に非常に役立ちます。
従来、要件は要件定義書（例えば、ワープロソフトや表計算ソフトなど）に記述されてきた。要件定義書（およびソフトウェア文書全般）の複雑化と変化に対応するため、データベース中心のシステムや専用の要件管理ツールが推奨されている。
アジャイルソフトウェア開発では、要件は多くの場合、受け入れ基準を伴うユーザーストーリーとして表現されます。ユーザーストーリーは通常、機能、つまりエピックの一部であり、ビジネス要件に基づいてユーザーに特定の価値を提供する、より広範な機能または関連する機能の集合です。
アーキテクチャドキュメント（ソフトウェアアーキテクチャ記述とも呼ばれる）は、特殊な設計ドキュメントの一種です。ある意味で、アーキテクチャドキュメントはコードから派生した3次派生文書と言えます（設計ドキュメントは2次派生文書、コードドキュメントは1次派生文書）。アーキテクチャドキュメントには、コードに特化した記述はほとんどありません。これらのドキュメントは、特定のルーチンのプログラミング方法や、ルーチンがなぜそのような形式になっているのかを説明するのではなく、ルーチンが存在する動機となる一般的な要件を列挙するだけです。優れたアーキテクチャドキュメントは、詳細には乏しいものの、説明は豊富です。下位レベルの設計アプローチを提案することはあっても、実際のトレードオフ分析は他のドキュメントに任せるべきです。
もう一つの設計文書の種類は、比較文書、またはトレードオフ分析です。これは多くの場合、ホワイトペーパーの形式をとります。システムの特定の一側面に焦点を当て、代替案を提案します。これは、ユーザーインターフェース、コード、デザイン、あるいはアーキテクチャレベルのいずれにも該当します。現状を概説し、一つまたは複数の代替案を説明し、それぞれの長所と短所を列挙します。優れたトレードオフ分析文書は、綿密な調査に基づき、難解な専門用語に頼らずに（読者を惑わすことなく）アイデアを明確に表現し、そして何よりも公平です。最良の解決策として提示するソリューションのコストを、正直かつ明確に説明する必要があります。トレードオフ分析の目的は、特定の見解を主張することではなく、最良の解決策を考案することです。結論を述べないこと、あるいはどの代替案も現状維持よりも十分に優れておらず、変更する価値がないと結論付けることも許容されます。これは、マーケティング手法としてではなく、科学的な取り組みとして取り組むべきです。
エンタープライズソフトウェア開発における設計ドキュメントの非常に重要な部分の一つが、データベース設計ドキュメント（DDD）です。DDDには、概念設計要素、論理設計要素、物理設計要素が含まれています。DDDには、データベースを操作する人々が必要とする正式な情報が含まれています。DDDを作成する目的は、関係者全員が利用できる共通の情報源を作成することです。潜在的なユーザーは次のとおりです。
リレーショナルデータベースシステムについて説明する場合、文書には以下の内容を含める必要があります。
シーンに登場するすべての俳優が使用するすべての情報を含めることは非常に重要です。また、データベースに変更が生じた場合は、ドキュメントもそれに合わせて更新することが非常に重要です。
ソースコードに関連付けられたコードドキュメント（READMEファイルやアプリケーションプログラミングインターフェイス ( API ) ドキュメントなど）は、徹底的であるべきですが、冗長すぎて保守に時間がかかりすぎたり、困難になったりしないようにすることが重要です。さまざまなハウツーや概要ドキュメントガイドは、 API 作成者によって文書化されているソフトウェアアプリケーションまたはソフトウェア製品に特化してよく見られます。このドキュメントは、開発者、テスター、エンドユーザーが使用できます。今日、多くのハイエンドアプリケーションは、電力、エネルギー、輸送、ネットワーク、航空宇宙、安全、セキュリティ、産業オートメーション、その他さまざまな分野で見られます。アーキテクチャの変更に伴い、基本的な情報と高度な情報が時間の経過とともに変化する可能性があるため、このような組織では技術ドキュメントが重要になっています。優れたコードドキュメントが存在すると、ソフトウェアの保守コストが実際に削減されるという証拠があります。[ 1 ]
コードドキュメントは、プログラマーが任意の関数やクラスを素早く検索できるように、リファレンスガイド形式で構成されていることが多い。
多くの場合、Doxygen、NDoc、Visual Expert、Javadoc、JSDoc、EiffelStudio、Sandcastle、ROBODoc、Plain Old Documentation (POD)、TwinText 、Universal Reportなどのツールを使用してコードドキュメントを自動生成できます。つまり、ソースコードからコメントやソフトウェア契約（利用可能な場合）を抽出し、テキストファイルやHTMLファイルなどの形式でリファレンスマニュアルを作成します。
ドキュメントの自動生成というアイデアは、プログラマーにとって様々な理由から魅力的です。例えば、ソースコードから（コメントなどを通じて）抽出されるため、プログラマーはコードを参照しながらドキュメントを作成でき、ソースコードの作成に使用したのと同じツールを使ってドキュメントを作成できます。これにより、ドキュメントを最新の状態に保つことがはるかに容易になります。
考えられる欠点としては、この種のドキュメントを編集できるのはプログラマーのみであり、出力の更新もプログラマーに委ねられている点が挙げられます（例えば、cronジョブを実行してドキュメントを毎晩更新するなど）。しかし、これを欠点ではなく利点と捉える人もいるでしょう。
著名なコンピュータ科学者であるドナルド・クヌースは、ドキュメント作成は後回しにすると非常に困難な作業になりかねないと指摘し、ソースコードと同じ場所、同じ時間に記述され、自動的に抽出されるリテラルプログラミング（LP）を提唱している。プログラミング言語のHaskellとCoffeeScriptには、LPの簡易版をサポートする機能が組み込まれているが、広く利用されているわけではない。
同じ方向性における、より厳密で徹底的な手法の進歩が、Docs as Codeである。
解説型プログラミングは、実際のプログラミング環境におけるリテラルプログラミングの実践的な応用から生まれたものです。解説型パラダイムでは、ソースコードとドキュメントを別々に保存することを推奨しています。
ソフトウェア開発者は、ソースファイル自体には含まれない情報を作成したりアクセスしたりする必要がある場合がよくあります。このような注釈は通常、コードウォークや移植など、サードパーティのソースコードを機能的に分析するソフトウェア開発活動の一部です。したがって、注釈は、正式なドキュメントシステムでは開発の妨げとなるようなソフトウェア開発のあらゆる段階で開発者を支援することができます。
コードドキュメントとは異なり、ユーザードキュメントはプログラムの使い方を単純に説明するものです。
ソフトウェアライブラリの場合、コードドキュメントとユーザードキュメントは場合によっては実質的に同等であり、統合する価値があるかもしれないが、一般的なアプリケーションでは必ずしもそうとは限らない。
通常、ユーザーマニュアルはプログラムの各機能を説明し、ユーザーがこれらの機能を理解するのに役立ちます。ユーザーマニュアルは分かりやすく、最新の状態であることが非常に重要です。ユーザーマニュアルは特定の形式で整理されている必要はありませんが、詳細な索引が付いていることが非常に重要です。一貫性と簡潔さも非常に重要です。ユーザーマニュアルは、ソフトウェアの動作を規定する契約書とみなされます。APIライターは、ソフトウェアのアーキテクチャと使用されているプログラミング技術に精通しているため、優れたユーザーマニュアルを作成する能力に非常に優れています。テクニカルライティングも参照してください。
ユーザー向けドキュメントは、さまざまなオンライン形式や印刷形式で作成できます。[ 2 ]ただし、ユーザー向けドキュメントは主に次の3つの方法で構成できます。
ソフトウェアのドキュメントに関してユーザーからよく聞かれる不満は、これら3つのアプローチのうち1つしか採用されず、他の2つがほとんど無視されているという点です。パーソナルコンピュータ向けのソフトウェアドキュメントは、コマンドやメニュー項目に関する参考情報のみを提供するオンラインヘルプに限定されるのが一般的です。新規ユーザーへの指導や、経験豊富なユーザーがプログラムを最大限に活用できるよう支援する役割は、ソフトウェア開発者から多大な支援を受けている民間出版社に任されています。
他の形式の技術文書と同様に、優れたユーザー文書も組織的な開発プロセスによって恩恵を受ける。ユーザー文書の場合、業界で一般的に行われているプロセスは、次の 5 つのステップで構成されている。[ 5 ]
多くのアプリケーションでは、一般の人が製品についてより深く知るように促すためのプロモーション資料が必要です。この種のドキュメントには、次の3つの目的があります。
「開発者の間でドキュメント作成に対する抵抗感があることはよく知られており、改めて強調する必要はない。」[ 10 ]この状況はアジャイルソフトウェア開発ではよくあることで、これらの手法は直接的な価値を付加しない不必要な活動を避けようとするからです。アジャイルマニフェストは「包括的なドキュメントよりも動作するソフトウェア」を重視することを提唱していますが、これは「私たちはすべての時間をコーディングに費やしたい。覚えておいてほしいのは、真のプログラマーはドキュメントを書かないということだ。」と皮肉に解釈される可能性があります。[ 11 ]
しかし、ソフトウェアエンジニアリングの専門家を対象とした調査では、アジャイル開発においてドキュメント作成が不要とは決して考えられていないことが明らかになった。とはいえ、開発にはモチベーションの問題があり、アジャイル開発に合わせたドキュメント作成方法（例えば、評判システムやゲーミフィケーションなど）が必要になる場合があることは認められている。[ 12 ] [ 13 ]
Docs as Codeは、ソフトウェアコードと同じ厳密さとプロセスでドキュメントを扱うシステムです。これには以下が含まれます。
ドキュメントをコードとして活用することとアジャイル開発手法を組み合わせることで、高品質で最新のドキュメントを維持するための堅牢なフレームワークが構築されます。
両者は以下のように統合できる。