KB(技術情報)の作成指針

これは、技術情報の作成に協力して下さる方向けの文書です。
以下は指針ですので、記述の際に、必ずしも遵守して頂く必要はありません。現状は細かい形式の調整よりも、内容の拡充を優先したいと考えています。

基本的には、HTMLファイルの形式で記載して頂くと助かります。テキストのみでも構いませんが、可能な限りHTMLファイルでの作成をお願いします。
詳細な説明は、以下に記述していますが、とりあえず記述したいという方のためにテンプレートファイルを用意していますので、ご参照下さい。

テンプレートのHTMLファイル
Internet Explorer の場合、勝手にHTMLファイルだと判別されてしまいます(-_-;
これは、現状回避できないので、ダウンロードの上ご参照ください。
上記のファイルの実際の表示

なお、全体としてのイメージは、Microsoft社の技術情報をベースにしていますので、適宜参照して下さい。以下に幾つか例を示します。

文書内容に関する注意点

以下、最低限記述して欲しい内容について説明します。
不明な点については、過去のKBを参考にして、基本的には各自の判断にしたがって記述して頂いて結構です。
どうしても不明な点、または統一した方がよいと思われる点につきましては、適宜 sugj-doc ML にて提案して頂ければと思います。

タイトル
タイトルには内容を端的に表したものを作成して下さい。
最終更新日
20yy/mm/dd 形式で記述します。
作成者
作成者の名前、またはハンドルネームを記述します。
なお、同一作成者の場合、可能な限り同一の名前もしくはハンドルネームを利用することを希望しますが、特に当方で確認などは行ないません。
最終更新者
作成者と最終的に更新した人が異なる場合に記載します。

適合プロダクト
文書の該当するプロダクトを「この文書は、以下のプロダクトに付いて説明したものです。」という言葉に続いて記述します。
記述方法に付いて、厳格には規定していませんが、おおむね以下の指針に従って、ください。不明な点は現状のKBなどを参考にして各自の判断で記述して下さい。

新しいプロダクト名をより上位に記述する
Samba以外のプロダクトよりは、Sambaを上位に記述する

プロダクト名は、基本的にベンダのWebページなどで正式に利用されている通称で記載する。
例えば Win2k-PRO SP2ではなく、Windows 2000 Professional SP2 と記載します。なお、不明な点については各自の判断で記述して下さい。
Samba については、以下のようにしてください。

記述形式	内容
Samba 2.2.x	Samba 2.2系全般
Samba 2.2 系列	Samba 2.2 系全般。今後は 2,2,x という記述に代わって、こちらを利用して下さい。
Samba 2.2.1a以前	Samba 2.2.1a (日本語版を含む)以前
Samba 2.2.1a (オリジナル版のみ)	Samba 2.2.1a で、日本語版は該当しない場合
Samba 2.0.10日本語版以降	Samba 2.0.10日本語版以降のSamba 2.0系列の日本語版でリリースはとわない
Samba 2.0.10日本語版リリース1.2	Samba 2.0.10日本語版リリース1.2 (samba-2.0.10-ja-1.2)

Microsoft社のプロダクトについては、Microsoft社の技術情報にて記載されている形式に準拠して下さい。なお、特定バージョンでしか確認が行なえないという場合は、そのバージョンのみを記載して頂ければ結構です。例えば、Samba 2.2.1a と Samba 2.2.4 でのみ動作確認を行なったという場合は、その二つのみを記載して頂ければ結構です。

内容欄
基本的には、以下のような順序で項を立てて文書を記述して下さい。
- 「現象」 - 「詳細」 - 「原因」 - 「対応策」
- 「概要」 - 「詳細」 - 「原因」 - 「対応策」
- 「概要」 - 「説明」
なお、内容によって一部の項目を省略しても構いません。
実際の内容については、自由に記述して下さい。
参照元
多くのKBはメーリングリストなどでの議論が元となっています。そういったオリジナルの議論に関する情報について、以下のような形式で記載をお願いします。
- 「この技術情報は、samba-jp:xxxxxx 、sugj-tech:xxxxx から始まる一連のスレッドの議論を元に作成されています。」
また、参考資料として外部の情報を示す場合は、文中で適宜示しても、最後に「参考情報」のような項を設けて、一括して示してもかまいません。
なお、特に参照元の情報がない場合は、記載しなくても結構です。

HTMLレベルでの方針

以下、HTMLレベルでの方針に付いて解説します。
なお、Samba-JP側でWebページへの記載時に適宜この方針に合致する形での修正を行ないますので、HTMLエディタを利用しているので良くわからないという方は、気にしなくても結構です。
不明な点については、過去のKBを参考にして、基本的には各自の判断にしたがって記述して頂いて結構です。
どうしても不明な点、または統一した方がよいと思われる点につきましては、適宜 sugj-doc ML にて提案して頂ければと思います。
なお、全体としてのイメージは、Microsoft社の技術情報をベースにしていますので、適宜参照して下さい。

英数字は半角で
全角の英数字は、引用の場合を除き、極力避けてください。
改行に付いて
エディタ側の都合などで全角40文字程度で改行するのは、極力避けて下さい。
半角カタカナは避ける
半角カタカナは避けて下さい。なお引用元が半角カタカナを利用している場合は、例えば以下のように記載して回避して下さい。
```
    「Microsoftネットワーククライアント(実際は半角カタカナ)」
```
文字コードはJISで
文字コードの変換は、Samba-JP側で行なえますので、気にしなくて結構ですが、機種依存文字や半角カタカナなどが入らないようにだけは注意して下さい。
ヘッダとフッタに付いて
Samba-JPのWebページにおけるヘッダとフッタについては、include 文により表示しています。そのため、ここに入れて頂く必要はありません。その他細かい点については、テンプレートファイルを参照して下さい。
図の扱い
基本的に、図を直接 KB 中で表示することは避けて下さい。必ず図のファイルへのリンクを作成して、明示的にクリックすることで図が表示されるようにして下さい。
同じ趣旨で、図を参照しないとわからない記述は極力避けて下さい。

作成したKBの登録

作成したKBは、sugj-doc メーリングリストでアナウンスして下さい。方法は、直接ファイルを添付して頂いても、Webサイトへのリンクでも構いません。その際 Subject に、[KB draft] のように書いていただくと、わかりやすいと思います。1日待って特にコメントがなければ、Webスタッフの方によって、随時Samba-JPのWebサイトに登録されます。

Webスタッフの方は、KBの登録と同時に、以下の作業を行なって下さい。

作成したKBをCVSに登録する
最終更新日、最終更新者、参照情報などを確認して適切な値に修正して下さい。
文字コードの変換や、ヘッダ、フッタの挿入など、HTMLレベルでの整形を随時行なって下さい。
登録時には、HTMLファイルに必ず実行属性を付けて登録して下さい。 実行属性がないと、Apache の XBitHack 機能が動作せず、include 文が機能しません。
KBの番号の発行については、今後も継続して記述したいという方には、100番単位で新規に割り当て、そうでない方には、200番台に追加していって下さい。
KBのインデックスファイルを更新する
トップページの新着情報を更新する
この際、掲載されてから1カ月を経過したものは、随時トップページから削除して下さい。