マニュアル環境とマニュアルの書き方- GLOBALBASE PROJECT

GLOBALBASEマニュアル集 >> マニュアル環境とマニュアルの書き方
2007-11-04版

マニュアル環境とマニュアルの書き方

著者:　森　洋久 / joshua＠globalbase.org 　※　

* 目的と概要
* このマニュアルを読むために必要な知識
* 前提となるシステム用件
* GLOBALBASEマニュアル環境の概念
* マニュアル環境における基本的なディレクトリとファイル
* マニュアルの基本的な形式
* マニュアルに最低限求められること
* XMLオリジナルファイルのファイル名
* 文章記述用タグ
* あたらしいマニュアルを一つ追加する手順
* 既にあるマニュアルを編集する手順
* バグレポートの記述方法(新たなバグレポートを追加する)
* バグレポートの記述方法(バグレポートアイテムを更新する)
* マニュアル文章に図や表を挿入する方法
* mmake時エラーリファレンス
* マニュアルXMLデータ形式
* マニュアルXML文章記述タグ
* マニュアル環境のスクリプト
* 履歴

目的と概要

gbs/doc/xml	ディレクトリ	マニュアル環境のディレクトリ
gbs/doc/xml/makefile	ファイル	mmake用makefile
gbs/doc/xml/make.html.sh	ファイル	公開用htmlディレクトリの作成
gbs/doc/xml/src/xml	ディレクトリ	オリジナルXMLファイルの配置場所
gbs/doc/xml/src/images	ディレクトリ	オリジナルイメージファイルの配置場所
gbs/doc/xml/src/tex	ディレクトリ	オリジナルTeX (BiB) ファイルの配置場所
gbs/doc/xml/src/html	ディレクトリ	オリジナルHTMLファイルの配置場所
gbs/doc/xml/utils	ディレクトリ	環境コンパイル用各種ファイル
gbs/doc/xml/work/xml	ディレクトリ	中間ファイルの配置場所
gbs/doc/xml/man	ディレクトリ	最終マニュアルドキュメント配置場所
gbs/doc/xml/man/html	ディレクトリ	HTML文書の生成場所
gbs/doc/xml/man/pdf	ディレクトリ	PDF文書の生成場所

表(ディレクトリ構成)はマニュアル作成のためのマニュアル環境のディレクトリ構造です。これは、ver.B.b11以降のGLOBALBASEのソースコードをダウンロードするか、あるいは、CVSをチェックアウトすると、その中にあります。さらにマニュアル環境は

GLOBALBASEの開発環境に含まれる mmake の機能
文献「GLOBALBASEの開発」を参照して開発環境をインストールしてください。
LANDSCAPEサーバにある exlエージェント [UNDEF REF (exl)]
文献「LANDSCAPEスタートアップ・マニュアル」を参照してLANDSCAPEサーバをインストールしてください。サーバを動作指せる必要はありません。
platex
TeXのホームページを参照してインストールしてください。

を利用して構築されています。従って、この３つの環境を構築する必要があります。

▲ページトップへ戻る

マニュアルの基本的な形式

マニュアルを一般的なワードプロセッサを使わずXMLで書く理由には、自動変換可能にするという目的の他に、XMLのタグにより一定の型を与え、余分なことが出来ないようにすることにより、すべてのマニュアルが統一的なフォーマットになるように方向付ける目的があります。GLOBALBASEのXML文書のマニュアルでは、マニュアルの記述をいくつかに分類し、体系化したものをタグ化してあります。まず、どのマニュアルにも必ず求められる事項として、

目的と概要 ( target)
人的要求事項 ( human-requirement)「このマニュアルを読むために必要な知識」
システム用件 ( machine-requirement)「前提となるシステム用件」
履歴 ( history)

があります。目的と概要はこのマニュアルが目的としてるところを簡潔に記述した物です。人的要求事項は、このマニュアルを読む人が前提として持っているべき知識を簡単に説明した物です。また、システム用件は、マニュアルを読む段階で備わっているべきソフトウエアやハードウエアが記載されています。もしこの記述に漏れた物があれば、マニュアルを読む人は、あらかじめ必要なソフトウエアをインストールしたり、あるいは知識をつけるべく他のマニュアルや文献を読む必要があります。最後に、マニュアルがいつどのように加筆訂正されたかについて簡単にまとめられた物が、履歴です。目的と概要、人的要求事項とシステム用件は、マニュアル環境によってマニュアルの冒頭にくるように制御されます。一方、履歴はマニュアルの末尾にくるように制御されます。

これに続き、説明事項 (section) が続き、そのあとにマニュアルの本文が続きます。マニュアルの本文部分では、そのマニュアルの目的とすることによっていくつかの特徴あるパターン、形式が存在します。現在用意されている基本的なパターンは現在以下の３つです。

シーケンスパターン ( sequence-man)
主にインストールや数々の操作の手順を記述するパターンを与えるものです。その他にも、概念の順序立てた説明などにも用いられます。一つ一つのステップを記述するタグと、「注意点」や「参考」などトピックを与えるタグが用意されています。
リファレンスパターン ( reference-man)
いわゆるリファレンスマニュアルを作成するときのパターンです。リファレンスマニュアルとはひとまとまりの複数の機能や概念を列挙したもので。個別の機能の間には順序関係などは存在しません。そのかわり、各機能を特徴づける、「プロトタイプ」「引数」「説明」などの項目はどの機能にも記述されている必要があります。ある機能では「引数」の項目はあるが別の機能では「引数」について説明されていない、といったことはあってはなりません。
一方で、エラーメッセージのリファレンスマニュアルと、ライブラリ関数のリファレンスマニュアルでは必要な項目が異なります。そのため、何種類かのリファレンス項目セットが用意されています。
トラッキングパターン ( tracking-man)
例えば、バグレポートはこのパターンに属します。初期報告があり、これに対する最初の所見、経過報告、最終報告、といった一連のreportの集合体が一つのアイテムとなり、このアイテムが複数集まったのが一つのトラックです。バグレポートは一番複雑なトラッキングですが、Q and Aも、一番単な、つまり「初期報告」＝Qと「最終報告」＝Aしかないトラッキングパターンと考えられます。
現在サポートされているトラッキンバターンは、バグレポート ( bugs)、新機能解説 ( function)、チューニング ( tuning)および、Frequency Ask of Question ( faq)です。

これらのパターンは、一つのマニュアルの中に、あっても無くてもよく、または、同じパターンが複数存在してもかまいません。異なるパターンが存在していてもかまいません。しかし、 これ以外のパターンでマニュアルを記述することは認められません。 もし、現在のこのパターンではどうしても記述出来ないパターンが発見された場合は、そのパターンの必要性をGLOBALBASEコミュニティーでよく議論し、新たにパターンを加える作業が必要です。なお現在、これらの章立ての方法については、もう少しフレキシブルに変更出来る機能を準備する必要があるかと考えています。例えば複数のシーケンスパターンをあわせて一つの章にするか、あるいは、現在のように別々の章にするかといった機能です。

また、異なるパターンが一つのマニュアルに混在する場合は、パターンの出現順番が、上記箇条書きの順番にマニュアル環境によって制御されます。こうすることによってマニュアルのどこに何が書かれているか、読者に容易に予想出来る読みやすいマニュアルが作成可能となります。

▲ページトップへ戻る

マニュアルに最低限求められること

一冊のマニュアルはシステムについての使い方と機能の説明です。使い方は、一つあるいは複数の使う目的を達成するため、それぞれの目的ごとに手順を示すものです。従って、これらにはシーケンスパターンの章を割り当てます。一方、機能の説明は、そのシステムの持っている機能をすべて列挙し説明するものです。これをリファレスパターンで記述します。機能の説明のためには、機能そのもものに目が奪われがちですが、機能実現に必要なデータ構造、および機能の利用時に発生するエラーの情報が必要です。つまり、データ構造およびエラーの種類および説明もリファレンスパターンで記述します。マニュアルには以下の説明が最低限収まっている必要があります。

目的別手順の説明　シーケンスパターンを使う。
機能の説明　リファレンスパターンを使う。
エラーの説明　リファレンスパターンを使う。
データ構造の説明　リファレンスパターンを使う。

また、GUIの説明においても、これに従うべきです。GUIの操作の仕方は、1.になります。一方、システムが用意するウィンドウやダイアログについて、リファレンスを作成すべきです。また、なんらかのGUI操作において発生するエラーダイアログについてはエラーのリファレンスが必要です。

GUIはデータ構造に直接触れないで操作出来るというところがメリットでありますから、GUIの場合データ構造に関するリファレンスはあまり利用しないかもしれません。しかしながら、セーブされるファイルがどんな形式かなど説明しておく必要があります。

リファレンスパターンにおいて、説明対象ごとに若干項目が異なります。その項目セットとして以下のものが用意されています。

function-xl
XL関数の機能説明の項目セット
function-script
スクリプトの機能説明の項目セット
function-xml
XMLデータ構造を説明するための項目セット
function-xml-err
エラー特にXLなどで発生するXMLパターンのエラーを説明する盲目セット。しかし、XLやXMLに限らず、エラーに関してはこの盲目セットが利用出来る見通しである。

一方、以下の項目セットは現在 ( ver.B.b11.02時点)ではサポート計画中であるが未サポートです。

function-window
ウィンドウの説明項目セット

以上、基本的に最低限必要なパターンを説明しましたが、これに説明を助ける補足情報としてQ and AやFAQ、バグ情報などをトラッキングパターンで追加して行くことも可能です。

▲ページトップへ戻る

XMLオリジナルファイルのファイル名

XMLオリジナルのファイルはver.B.XX.XX/doc/xml/src ( gbs/doc/xml/src ) の中にはいっています。日本語のマニュアルに関しては、ja-**.xml というファイル名になっています。最初のjaは日本語を表します。en-は英語、cn-は中国語ということになっています。基本的にISOの国名記述の標準に順処します。

しかしながら、現在のところは、日本語のマニュアル環境しか準備していません。追って、英語等を準備して行く予定です。

▲ページトップへ戻る

文章記述用タグ

マニュアルをXMLで記述する場合、改行やイタリック体、ボールド体など基本的な文章制御の方法が必要です。GLOBALBASEのマニュアル環境では、HTMLの基本的なタグをこれに踏襲しました。たとえば、改行は、<br/>タグを使います。イタリックは、「<it>italic</it>」と記述すれば、「 italic 」と表示されます。その他にも、アイテマイズ、表、図があります。しかしPDFをHTMLを同時に出力することを目的としているため、HTMLのタグとは属性の与え方などが微妙に異なります。これらについて詳しくは「マニュアルXML文章記述タグ」を参照してください。図の挿入のしかた、あるいは、表の挿入の仕方等、よく使うと思われるタグについては別の章立てで手順の説明を行っています。

▲ページトップへ戻る

履歴

日時:2007-11-04
マニュアル生成。(2007-11-04版)
--
日時:2006-08-16
著者:森　洋久 / 反映されたバージョン:ver.B.b11.02
このマニュアルを作成
--
日時:2006-08-20
著者:森　洋久 / 反映されたバージョン:ver.B.b11.02
このマニュアルの最初の記述の完了。
--
日時:2006-09-10
著者:森　洋久 / 反映されたバージョン:ver.B.b12
trackingの新機能report-type="function"の記述を追加。
--
日時:2006-09-11
著者:森　洋久 / 反映されたバージョン:ver.B.b12
trackingの新機能report-type="faq"の記述を追加。
--
日時:2006-11-02
著者:森　洋久 / 反映されたバージョン:ver.B.b13.02
trackingの新機能report-type="tuning"の記述を追加。
--

▲ページトップへ戻る

$GLOBALBASE��AI[v\[XE\tgEFAxvOSOURCEFORGE.JP��QBĂ܂B$