[an error occurred while processing this directive]
日本 Samba ユーザー会

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

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

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

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

  1. Microsoft社の技術情報
  2. Samba-JPの技術情報

文書内容に関する注意点

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

  1. タイトル
    タイトルには内容を端的に表したものを作成して下さい。
  2. 最終更新日
    20yy/mm/dd 形式で記述します。
  3. 作成者
    作成者の名前、またはハンドルネームを記述します。
    なお、同一作成者の場合、可能な限り同一の名前もしくはハンドルネームを利用することを希望しますが、特に当方で確認などは行ないません。
  4. 最終更新者
    作成者と最終的に更新した人が異なる場合に記載します。
  5. 適合プロダクト
    文書の該当するプロダクトを「この文書は、以下のプロダクトに付いて説明したものです。」という言葉に続いて記述します。
    記述方法に付いて、厳格には規定していませんが、おおむね以下の指針に従って、ください。不明な点は現状の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 でのみ動作確認を行なったという場合は、その二つのみを記載して頂ければ結構です。
  6. 内容欄
    基本的には、以下のような順序で項を立てて文書を記述して下さい。
    • 「現象」 - 「詳細」 - 「原因」 - 「対応策」
    • 「概要」 - 「詳細」 - 「原因」 - 「対応策」
    • 「概要」 - 「説明」
    なお、内容によって一部の項目を省略しても構いません。
    実際の内容については、自由に記述して下さい。
  7. 参照元
    多くのKBはメーリングリストなどでの議論が元となっています。そういったオリジナルの議論に関する情報について、以下のような形式で記載をお願いします。
    • 「この技術情報は、samba-jp:xxxxxx 、sugj-tech:xxxxx から始まる一連のスレッドの議論を元に作成されています。」
    また、参考資料として外部の情報を示す場合は、文中で適宜示しても、最後に「参考情報」のような項を設けて、一括して示してもかまいません。
    なお、特に参照元の情報がない場合は、記載しなくても結構です。

HTMLレベルでの方針

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

作成したKBの登録

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

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


ミラーサイト: [ WWW: master ] [ FTP: ring | kddilabs | plathome | mex | master ]

Copyright © 1999-2021 日本 Samba ユーザー会 (Samba-JP)
2011-12-19 01:17:52 JST 更新