ソフトウェアドキュメンテーション

ソフトウェアドキュメンテーションとは、コンピュータのソフトウェアに付随する文書、またはそのような文書を作成することを意味する。類似の用語としてソースコードドキュメンテーションがある。

仕様書を含むか、含まないかは立場により異なる。仕様書は設計/実装のために事前または事後に作成する文書である。ドキュメンテーションは開発中あるいは既に完成したソフトウェアに付随する文書を指す訳ではない。ソフトウェアに関する文書には作成する順番があるとは限らない。図からソフトウェアを生成する場合もあれば、ソフトウェアから図を生成する場合もある。ソフトウェアから仕様を生成する場合もあれば、仕様からソフトウェアを生成する場合もある。

ドキュメンテーションの分類

ドキュメンテーション︵文書化︶はソフトウェア開発の重要な部分を占めている。ISO/IEC 12207, ISO/IEC 15504 part5に文書化(documentation process)を定義している。見過ごされることが多い。ドキュメンテーションは以下のように分類できる:

●制約・要求 - ソフトウェアの制限、実現不可能な事項と、費用投資可能な機能などを明確にする文書。仕様書を含む。

●アーキテクチャ/設計 - ソフトウェアの概要。外部環境との関係、設計原則などが記述する文書。

●技術 - コード、アルゴリズム、インタフェース、APIなどの文書。

●エンドユーザー - エンドユーザー向けのマニュアル、システム管理者やサポートスタッフ向けの文書。

●マーケティング - 製品概要などのプロモーション用文書。

制約・要求

requirementをしばしば要求と訳すことがあるが、厳密には必要事項であり、制約を含む。 必要事項を記述したものを仕様と呼ぶこともある。 仕様を記述するとそのまま動作する仕組みもあり、何が仕様で何がソフトウェアかは仕組みごとに確認するとよい。

アーキテクチャ/設計文書

設計文書は様々な形式がある。どのように︵HOW︶使うのかよりも、なぜ︵WHY︶そのように設計されているかを解説することに注力していることが多い。例えば、データ構造がそのようになっている背景となる原理を解説したり、特定オブジェクトのメンバー関数をリストアップしたり、コードの追加方法を記述したりする。あるクラスがなぜそのように構成されているかを説明し、パターンを示し、よりよい方法の概略を提案したり、今後の改善を提案したりする。これらは、コードに関する文書やユーザー向け文書には不適切だが、設計にとっては重要である。

アーキテクチャ文書は設計文書の特殊例である。ある意味で、アーキテクチャ文書はコードからの第3の生成物︵第1はコードに関する文書、第2は設計文書︶である。アーキテクチャ文書にはコードに固有な部分はほとんどない。特定のルーチンのプログラム方法を説明することはほとんどなく、あるルーチンがなぜ現在のような形になっているかさえ説明しない。代わりにそのルーチンの存在意義や動機となった要求仕様などを解説する。よいアーキテクチャ文書は詳細に関しては紙幅を費やさず、解説に重きをおく。下位の設計の方針を示唆することもあるが、そこに踏み込むことはせず、他の文書に任せる。

その他の設計文書として類似製品との比較文書がある。これは﹁ホワイトペーパー﹂の形式となることが多い。ある特定の観点でシステムを論じ、代替手法を示唆する。その観点はユーザーインターフェイス、コード、設計、アーキテクチャなど様々である。現状を概説し、複数の代替手法を説明し、それぞれの長所と短所を列挙する。よい比較文書はしっかりした研究の上に成り立ち、考えを明確に述べ︵読者を戸惑わせる専門用語を使わず︶、何よりも公平である点が重要である。比較文書の目的は、特定の観点を押し付けるというよりも、最善の解決法を見出すことである。結論に至らない場合でも全く問題はなく、現在の状況を改善するような代替案が全くないという結論であっても構わない。比較文書はマーケティングの道具として最初から執筆するのではなく、あくまでも科学的な考察の上で書かれるのがよいとされる。

技術文書︵コード文書︶

これは、多くのプログラマが﹁ソフトウェアドキュメンテーション﹂という用語で想定している文書である。ソフトウェア開発では、コードだけでは不十分である。コードと共にそれをどう使うかといった様々な事柄を記述した文書が必要である。このような文書はソースコードに埋め込まれていることが多く、ソースコードを入手すれば同時に参照可能となることが多い。

この文書は非常に技術的で、主にAPI、データ構造、アルゴリズムなどを定義し解説する。例えば、m_name という変数が人間の名前を参照するものである、というような説明が書かれる。コード文書は完全であることが重要だが、同時に保守性を考慮して冗長性をなるべく排除しなければならない。

Doxygen、Javadoc、ROBODoc、POD、TwinText といったツールでコード文書を自動生成できる。これらツールはソースコードからコメントを抜き出して、テキストまたはHTMLの形式でリファレンスマニュアルを作成するものである。コード文書は﹁リファレンスガイド﹂のスタイルで構成されることが多く、プログラマが素早く任意の関数やクラスを検索できるようになっている。

多くのプログラマがいくつかの理由から文書の自動生成を活用している。例えば、ソースコードにコメントの形で文書が埋め込んであると、プログラマはコードを書くのに使っているツールで文書も同時に書くことができ、コードを見ながら文書を書くのに便利である。これにより、コードと文書を常に同時更新するのが簡単になる。

もちろん欠点もあり、プログラマ以外がこの形式の文書を編集できないという一面もあり、プログラマ以外はツールによって更新されるまで最新の文書を参照できない︵例えば、ソースからの文書生成は毎晩まとめて行われたりする︶。もっとも、このような特徴を利点と見る考え方もある。

ドナルド・クヌースは、ソフトウェアドキュメンテーションをコードを書いた後で行うのが非常に難しいと考え、文芸的プログラミングという手法で文書をソースコードと同時に書くようにして、自動的手段で文書をソースコードから抜き出すようにした。

ユーザー文書

ユーザー文書は一般にソースコードとは完全に分離したもので、単にそのプログラムの使用法を解説するものである。

ソフトウェアライブラリの場合、コード文書とユーザー文書は実質同じであるが、一般のアプリケーションではそうではない。一方で、LISPマシンでは全てのコードに文書が付随していた。これに強力な検索機能を組み合わせて、LISPマシンでは文書を検索して、そこから関連する関数名などをコピー&ペーストでユーザーが作成中のコードに直接利用することができる。このレベルの使い易さを実現した最近のシステムというものは見受けられない。

一般に、ユーザー文書はプログラムの機能毎にその機能を呼び出すのに必要な手順を説明している。よいユーザー文書はさらに、問題発生時の解決策を与えてくれる。ユーザー文書にとって重要なことは、紛らわしい記述を避けることと、付属するソフトウェアに正しく対応していること︵最新であること︶である。ユーザー文書の形式は定まっていないが、索引が非常に重要である。一貫性と単純性も重要である。ユーザー文書はソフトウェアの契約の一部を構成する。

ユーザー文書の形式として広く採用されている3つの形式がある。チュートリアル形式は新規ユーザーにとっては最も便利であり、特定のタスクを手順を追ってガイドしてくれる。テーマごとの文書形式は、章や節ごとに特定のテーマを解説したものであり、中級ユーザー向けと言える。最後の形式は、コマンドやタスクを単純に辞書的順序で並べたもので、通常それぞれの項目に関連項目への相互参照が記されている。これは自分がどういう情報を求めているか判っている上級ユーザー向けといえる。実際の製品では、これら3つの形式の文書が同時に付属することはあまりないため、ユーザーがその点に不満を持つこともある。

ユーザー文書の提供形式として、パーソナルコンピュータ上のオンラインヘルプしか用意せず、コマンドやメニュー項目に関する情報しか与えないということも多い。この場合、チュートリアルや詳細な情報は、ソフトウェア開発者から特別な支援を受けた出版業者が書籍の形で販売することが多い。

マーケティング文書

多くのアプリケーションでは、その内容を広く知ってもらうための宣伝目的の文書が必要となる。この形式の文書には以下の3つの目的がある:

(一)製品の潜在的ユーザーを刺激し、彼らにその製品をもっと知りたいと思わせる。

(二)製品が何をするのかを正確に知らせ、その製品を購入することで何が得られるのかを周知させる。

(三)他の類似製品との比較によって、その製品の位置づけを明らかにする。

よいマーケティング手法の1つは、覚えやすい﹁キャッチフレーズ﹂を使って伝えたい要点を明確にし、同じ業者の他の製品との相互運用性を強調することである。

アーキテクチャ/設計/技術文書のためのツール

• 統一モデリング言語（UML）

ソースコードからの文書生成ツール

• ApiGen - PHP
• Ddoc - D言語（GPL）
• Doxygen - 各種言語向け（GPL）
• Epydoc - Python（MIT License）
• HeaderDoc - Apple製、各種言語向け（APSL）
• Javadoc - Java
• Natural Docs - 各種言語向け（GPL）
• NDoc - 共通言語基盤向け（GPL）
• phpDocumentor - PHP（LGPL）
• ROBODoc - 各種言語向け（GPL）
• Sandcastle - C#, VB.NET 向け (Microsoft Public License)
• VBDOX - Microsoft Visual Basic（GPL）

ソフトウェア工学と文書化の方法論

• 文芸的プログラミング

関連項目

• ソフトウェア開発工程
• 契約プログラミング
• Docstring
• ドキュメンテーションジェネレータ