ソフトウェアドキュメンテーションとは、コンピュータのソフトウェアに付随する文書、またはそのような文書を作成することを意味する。類似の用語としてソースコードドキュメンテーションがある。仕様書とは異なることに注意されたい。仕様書は設計/実装のために事前に作成される文書だが、ここでいうドキュメンテーションは開発中あるいは既に完成したソフトウェアに付随する文書である。
目次
1 ドキュメンテーションの分類
2 アーキテクチャ/設計文書
3 技術文書（コード文書）
4 ユーザー文書
5 マーケティング文書
6 アーキテクチャ/設計/技術文書のためのツール
7 ソースコードからの文書生成ツール
8 ソフトウェア工学と文書化の方法論
9 関連項目
//
ドキュメンテーションはソフトウェア開発の重要な部分を占めているが、見過ごされることが多い。ドキュメンテーションは以下のように分類される:
アーキテクチャ/設計 - ソフトウェアの概要。外部環境との関係、設計原則などが記述される文書。
技術 - コード、アルゴリズム、インタフェース、APIなどの文書。
エンドユーザー - エンドユーザー向けのマニュアル、システム管理者やサポートスタッフ向けの文書。
マーケティング - 製品概要などのプロモーション用文書。
設計文書は様々な形式がある。どのように（HOW）使うのかよりも、何故（WHY）そのように設計されているかを解説することに注力していることが多い。例えば、データ構造がそのようになっている背景となる原理を解説したり、特定オブジェクトのメンバー関数をリストアップしたり、コードの追加方法を記述したりする。あるクラスが何故そのように構成されているかを説明し、パターンを示し、よりよい方法の概略を提案したり、今後の改善を提案したりする。これらは、コードに関する文書やユーザー向け文書には不適切だが、設計にとっては重要である。
アーキテクチャ文書は設計文書の特殊例である。ある意味で、アーキテクチャ文書はコードからの第3の生成物（第1はコードに関する文書、第2は設計文書）である。アーキテクチャ文書にはコードに固有な部分はほとんどない。特定のルーチンのプログラム方法を説明することはほとんどなく、あるルーチンが何故現在のような形になっているかさえ説明しない。代わりにそのルーチンの存在意義や動機となった要求仕様などを解説する。よいアーキテクチャ文書は詳細に関しては紙幅を費やさず、解説に重きをおく。下位の設計の方針を示唆することもあるが、そこに踏み込むことはせず、他の文書に任せる。
その他の設計文書として類似製品との比較文書がある。これは「ホワイトペーパー」の形式となることが多い。ある特定の観点でシステムを論じ、代替手法を示唆する。その観点はユーザーインターフェイス、コード、設計、アーキテクチャなど様々である。現状を概説し、複数の代替手法を説明し、それぞれの長所と短所を列挙する。よい比較文書はしっかりした研究の上に成り立ち、考えを明確に述べ（読者を戸惑わせる専門用語を使わず）、何よりも公平である点が重要である。比較文書の目的は、特定の観点を押し付けるというよりも、最善の解決法を見出すことである。結論に至らない場合でも全く問題はなく、現在の状況を改善するような代替案が全くないという結論であっても構わない。比較文書はマーケティングの道具として最初から執筆するのではなく、あくまでも科学的な考察の上で書かれるのがよいとされる。
これは、多くのプログラマが「ソフトウェアドキュメンテーション」という用語で想定している文書である。ソフトウェア開発では、コードだけでは不十分である。コードと共にそれをどう使うかといった様々な事柄を記述した文書が必要である。このような文書はソースコードに埋め込まれていることが多く、ソースコードを入手すれば同時に参照可能となることが多い。
この文書は非常に技術的で、主にAPI、データ構造、アルゴリズムなどを定義し解説する。例えば、m_name という変数が人間の名前を参照するものである、というような説明が書かれる。コード文書は完全であることが重要だが、同時に保守性を考慮して冗長性をなるべく排除しなければならない。
Doxygen、Javadoc、ROBODoc、POD、TwinText といったツールでコード文書を自動生成できる。これらツールはソースコードからコメントを抜き出して、テキストまたはHTMLの形式でリファレンスマニュアルを作成するものである。コード文書は「リファレンスガイド」のスタイルで構成されることが多く、プログラマが素早く任意の関数やクラスを検索できるようになっている。
多くのプログラマがいくつかの理由から文書の自動生成を活用している。例えば、ソースコードにコメントの形で文書が埋め込んであると、プログラマはコードを書くのに使っているツールで文書も同時に書くことができ、コードを見ながら文書を書くのに便利である。これにより、コードと文書を常に同時更新するのが簡単になる。
もちろん欠点もあり、プログラマ以外がこの形式の文書を編集できないという一面もあり、プログラマ以外はツールによって更新されるまで最新の文書を参照できない（例えば、ソースからの文書生成は毎晩まとめて行われたりする）。もっとも、このような特徴を利点と見る考え方もある。
ドナルド・クヌースは、ソフトウェアドキュメンテーションをコードを書いた後で行うのが非常に難しいと考え、文芸的プログラミングという手法で文書をソースコードと同時に書くようにして、自動的手段で文書をソースコードから抜き出すようにした。