Next: Manual Structure Details, Up: Documentation
GNUシステムの一部を文書にする好ましい方法はTexinfo整形言語
でマニュアルを書くことだ。Texinfoのマニュアルを、ハードコピーか、
info
やEmacsのInfoサブシステム(C-h i)を使って利用できるオン
ラインのバージョンで見なさい。
プログラマはしばしば、彼らが知っている実装の構造に従う文書を構成するのが 最も自然だと感じる。しかしこの構造はそのプログラムの使い方を説明するには 必ずしも良いとは言えない。それはユーザには関係がなく、ユーザを混乱させる かもしれない。
段落の文から別々のマニュアルに論題を分類することまで、あらゆる水準で、文 書を構成する正しい方法は、それを読むときにユーザが心に抱くであろう概念や 疑問に従う。ときどきこの考えの構造は文書化されるソフトウェアの実装の構造 と一致する。—でもしばしばそれらは異なる。しばしば良い文書を執筆するた めに学ぶ一番重要な部分は、実装のように文書を構成していて、もっと良い別の 構成について考えるときに気付くことを学ぶことだ。
例えば、GNUシステムのそれぞれのプログラムはおそらく一つのマニュアルに記 述されるべきだ。しかしこれはそれぞれのプログラムがそれ自身のマニュアルに 文書化されるべきであることを意味していない。このことはユーザが理解するの を助ける構造よりもむしろ、その実装の構造に従っているだろう。
代わりに、それぞれのマニュアルは密接な論題を包含するべきだ。例え
ば、diff
のマニュアルとdiff3
のマニュアルの代わりに、
cmp
だけでなく、これらのプログラム両方も包含する、“ファイルの比較”
のマニュアルが一つある。それらのプログラムを一緒に文書にすることで、全体
の主題をよりすっきりさせることができる。
プログラムを論じるマニュアルはそのプログラムのコマンドライン・オプション 全てとそのコマンド全てを記述すべきだ。それはそれらの使用例を与えるべきだ。 しかしマニュアルを機能の列挙として構成してはならない。代わりに、副題によっ て、論理的に構成しなさい。プログラムが行う仕事について考えるときにユーザ が尋ねるであろう質問を提出しなさい。
概して、GNUマニュアルは指導書と参考書の両方に役に立つべきだ。それはInfo によりそれぞれの論題に対する便利な手段のために、そして(付録は別として)通読 するために作り上げられるべきだ。GNUマニュアルは始めから通して読む初心者 への良い紹介を行うべきで、ハッカーが欲しがる詳細のすべてを与えるべきでも ある。
そのことは最初に思われるほど難しくない。それぞれの章をその論題の論理的な 分類として整理しなさい。しかしその節を整頓して、それらのテキストを執筆し なさい。その章を通読することが意味を為すように。その著書を章に構成すると きや、節を段落に構成するとき、同様にしなさい。その標語は、それぞれ の地点で、先行するテキストによって上げられた最も基本的で最も重要な話題を 提出しなさい、だ。
必要なら、マニュアルの最初に、純粋に指導的で、主題の基礎を包含する、余分 な章を入れなさい。これらは初心者がマニュアルの残りを理解するための枠組み を提供する。Bisonのマニュアルはこれの使い方の良い例を提供する。
GNUの文書を書き方の手本としてUnixのmanページを使ってはいけない。それらの ほとんどは簡潔で、構成が悪く、根底にある概念について不適切な説明を与えて いる。(もちろん例外はある。) またUnixのmanページはGNUマニュアルで使用す るものとは異なる、特有の構成を使用する。
Unixの文書で使われる“pathname”という用語を使わないでください。代わりに “file name”(二語)を使いなさい。“path”という用語は検索パスに対しての み使用し、それはファイル名のリストだ。
コンピュータ・プログラムへの間違った入力を表すのに、“illegal”という用 語を使わないでください。このためには“invalid”を使い、“illegal”という 用語は違法のために確保してください。