JF: JF Workshop Guidance: JF Project における文書作成の手順

Wed Mar 4 22:55:55 JST 2015
Contents:

JF-procedure

山崎@トロントさんの JF 文書 JF-procedure で、JF Project の文書作成作業で慣用的に使われている、 構想準備から公開までの手順が解説されています。 まずはこれを参照してください。

LDP 文書の翻訳手順

LDP の翻訳を行うときの基本的な手順です。

(オリジナルの文書を執筆する場合や LDP 以外(カーネル付属文書等)の翻訳をする場合も手順はほぼ同じなので、 適宜読み変えてください。)

作業のアウトライン

  1. 訳す文書を決める
  2. JF-in-progress のチェック
  3. JF-ML で作業を宣言する
  4. SGML 形式原文の入手
  5. 翻訳
  6. ドラフト投稿
  7. 著者への連絡と翻訳許可の取得
  8. 文書情報管理ファイルを用意する
  9. 正式版リリース
  10. メンテナンス

1. 訳す文書を決める

LDP のウェブページ (http://www.tldp.org/) で面白そうな文章、新しい文書を探します。

個人的な経験によると、 自分自身があまり興味を持てない文書に無理して手を出すとロクなことになりません (^_^;

2. JF in Progress のチェック

作業しようとしている文書について、 既に他の人が作業を行っていないかどうか確認します。

JF における LDP の翻訳状況は JF in Progress のページで、現在の作業状況がわかるようになっています。 JF-ML で翻訳予約宣言をすると、JF in Progress に反映されます。

日本語訳があるけれどバージョンが古い場合などは、 前の訳者に連絡して引き継ぎをするといいでしょう。 また、現在作業中ということであれば、 2 人で分担してしまえば文書のリリースを早くできるので、 JF の利用者のためになると思います。

3. JF-ML で作業を宣言する

作業のバッティングを避けるために予約をする…というより、 一緒に作業をする仲間を探す呼びかけを行う方が良いと思います。

ここで宣言された作業は、JF の Git リポジトリの予約ファイルに 記入され、JF in Progress に反映されます。Git に自分で commit 出来る方は、直接 予約ファイルに記入してください。

4. SGML 形式原文の入手

LDP のサイトからオリジナルの文書を入手します。 文書は色々なフォーマットで配布されているのですが、 特に理由のない限り SGML 形式のものを翻訳元原稿として使いましょう。 基本的には SGML がメインのフォーマットであり、 他の形式のものは SGML から変換して作成するからです。 JF Project が文書を管理する際にも SGML 形式の原稿を基本としています。

最新版の HOWTO 文書は cvs.tldp.org もしくは www.ibiblio.org で入手することができます.

5. 翻訳

翻訳作業では、元の文章をコメントアウトして日本語訳に置き換え、 対訳式のファイルにします。例えば、次のような感じになります :

     ----------------- ちょきちょき --------------------
       <!--
       This is a pen.
       -->
       これはペンです。
     ----------------- ちょきちょき ---------------------

このようにする理由は

  1. 原文が訳のすぐ近くに無いと、 他の人がチェックをするときにとても不便
  2. 実際に読まれる際の形式(テキスト、HTML 等)に変換すると、 どうせコメント部分は消えるので、邪魔にはならない
  3. バージョンアップの時に、 英文と並んでいた方が有利 (注 1)

などの理由があるからです。

当然ながら、文中にある SGML のタグはそのまま残します (SGML に関する情報は、 JF Guidance: SGML 文書作成 のページをご覧になってださい)。

また、翻訳作業中に分からない部分があれば気軽に JF-ML で質問をしましょう。 そのための JF-ML です。

早川@Asahiネット さんの JF 文書 JF 文書文体ガイド を一読しておくとよいでしょう。

複数のメンバで共同で翻訳をすすめる場合は、 JF の Git リポジトリ を利用すると、作業効率があがります。

6. ドラフト投稿

一通り訳し終わったら、この文書をドラフト扱いで JF-ML に投稿し、 他の人にチェックしてもらう段階です。もちろん完成度は高いに越したことは ないのですが、最初から完璧なドラフト原稿を用意するのは難しいでしょう。

特に原文に不明な点があったりすると、そこで引っ掛かって時間を浪費 してしまうことがあります。 あまり深く悩まずに、わからないところはわからない、 と SGML のコメントタグで記入して、JF-ML のメンバの知恵を借りるというのも 重要なテクニックのひとつです(^_^;

JF-ML にドラフト原稿を投稿するときは、 Subject に DRAFT の文字を入れるなどして、 原稿がドラフト段階であることを明確にわかるようにしてください。 原稿はメールの本文中にそのまま挿入して構いませんが、 どこからどこまでがドラフト原稿なのか、メールの地の文と区別がつくように してください。

MIME Multipart Mixed Message でドラフト原稿を添付しても構いませんが、 Base64 形式などでエンコードすると、デコードしない限り 原稿を読むことができません。 そのまま読める charset=ISO-2022-JP の text/plain 形式で添付するのが望ましいでしょう。

この段階であなたの原稿はドラフト扱いとなります。だいたい 1 週間ほどで ドラフトを読んだメンバから間違いの指摘やアドバイスをしてもらえるでしょう。

これらのコメントを原稿にどう反映させるかどうかは 執筆者の判断にまかされますが、 どのような判断を下したかを JF-ML に報告するのは、 コメントをしてくれた人に対する礼儀として忘れないようにしましょう。 また、チェックをしてくださった人に対しては、 文書のどこかに一言お礼を書いておくとよいでしょう。

逆に他の人が JF-ML にドラフトを投稿したら、 できる限り目を通してあげましょう。 自分の知らない分野の文書でも「てにをは」のチェックくらいはできますよね。

いずれにせよ、他のメンバからのコメントを参考にして、ドラフト原稿に 修正を加えていきます。修正がおわったら、再度ドラフトの第二版として JF-ML に投稿します。修正の必要がなくなったら、ドラフトの段階を終了します。

7. 著者への連絡と翻訳許可の取得

正式リリースまでに、 オリジナル版の著者に「公開しても良いか ?」 という確認のメールを出します。 LDP のライセンスは (ライセンスを変えない限り) 基本的には翻訳・配布は自由 というものなので、確認とは言っても単なるあいさつ程度と考えて構いません (注 2)。

連絡の際には、typo を指摘してあげたり、 さりげなく文書を誉めると喜ばれます (^_^). また、このように話を通しておくと、 新しいバージョンが出る時に 著者がこっちにも送ってくれるようにもなったりします。

8. 文書情報管理ファイルを用意する

JF Project では 文書を JF の Git リポジトリに格納する際に、 文書についての付帯情報を一緒に納めることになっています。 この文書情報管理ファイルは info ファイルと呼ばれています。 この info ファイルの記述によって、JF の Web 資源管理の中で、 各文書がどのように取り扱われるべきかを指定することができます。 (texinfo と混同しやすい名前ですが、JF Project では単に info と呼ぶときは、 通常この文書情報管理ファイルのことを指すことが多いです)。

ひとつの文書につき、 必ずひとつの info ファイルを用意します。 この info ファイルを第三者が記述するのは結構な労力を必要とするので、 文書作成者本人が正式版リリースまでに準備するようにしてください。 この作業は LDP の翻訳に限ったことではないのですが、 JF 資源の保守管理作業がすごく楽になるので、ぜひ協力をお願いします。

info ファイルのフォーマットなど詳細に関しては JF Workshop Guidance: 文書情報管理ファイル(info)について をご覧下さい。

9. 正式版リリース

ドラフトに対する訂正個所がなくなった、 と思ったら正式版としてリリースします。

リリースを行うには、必ずその旨を宣言して、 JF-ML にリリース版の文書を投稿します。 Subject: に RELEASE などの文字を入れて、 正式版であることがはっきりとわかるようにしてください。 (JF 文書のメンテナは常に募集中です :-))

JF の Git リポジトリ を利用して作業を進めてきた場合や、自分でリポジトリに commit できる という方は、Git リポジトリの README にしたがって、 登録作業を自分で行うこともできます。

10. メンテナンス

HOWTO 文書も鮮度が大事なので、 原文のバージョンが上がったらできるだけ追従しましょう。 原文のバージョンが上がったことを知る方法は大きく 3 つに分かれます :

忙しいなどの理由で作業できない場合には、 可能な限り JF でその旨を宣言し、 誰かに作業を引き継ぎましょう!

以上で手順の説明は終わりです。疑問点があれば、 JF-ML で気軽に質問してください。


注 1:

バージョンアップがあった時は、普通は英語版の新旧文書の diff を取り、 それを使って作業することになります。具体的には、diff の各項目について

を手作業で直します。 対訳形式になっていない場合には、 この時に直す場所を見つけるのが面倒になります。

注 2:

別の言い方をすると、拒否されるとか、 難しいライセンスの話になったりすることはまずあり得ません。 ですから英語のメールを書くのは苦手であっても、 次のようなテンプレートを利用するだけで大丈夫です。

------------------------ ちょきちょき ------------------------
Hello Mr. XXXX, I'm FUJIWARA Teruyoshi, a Japanese Linux user.

I would like to translate your "The TITLE of the HOWTO Document"
into Japanese and distribute it under your copyright notice. Is this
OK?

Thank you for your time,
--
FUJIWARA Teruyoshi

FYI:
  I am a member of the JF project, the Japanese equivalent of
  LDP. We make original Japanese FAQs, and have translated many
  LDP documents into Japanese.
------------------------ ちょきちょき ------------------------
  

Configure.help 翻訳作業

Linux Kernel を構築する際の、利用者の判断を助けるヘルプファイルが Configure.help です。 JF Project では、この Configure.help の翻訳・公開作業 も行っています。

他の文書と違い、Configure.help は翻訳作業をすすめながら、 作業途中でも暫定版として公開しています。 暫定版として公開するファイルは、 翻訳作業の進行状況 に応じて自動更新される仕組みになっています。 そのため、作業の手順も他の文書の作成とはちょっと異なる点があるので 注意してください。

Configure.help 翻訳作業の手順

  1. (a)Configure.help 翻訳作業の進行状況 を見て、翻訳する項目を選ぶ。
    [進行状況表の見方の解説]
    (b)あるいは、後述する Configure.help-2.4 翻訳作業キット, Configure.help-2.2 翻訳作業キット の最新のものを入手すると、 どの項目が未作業になっているのか、手元で確認できます。
          % make db (最初の一回だけ必要)
          % make status
    
  2. JF-MLで翻訳作業の予約をする。
    予約メールを流す際には、
    Subject: [CH:RESERVE] CONFIG_XXXXXXX CONFIG_XXXXXXX 2.2.2
    という風に、どの項目を翻訳するのか・どのバージョンに対し翻訳するのか分かるようにしてください。 同バージョンの複数項目に対する予約は一通のメールにまとめていただくと助かります。 この予約は Configure.help 翻訳作業の進行状況 にも 反映されます。
  3. 原文、暫定翻訳文など作業に必要なファイルを入手する。
    これにはいくつかの方法があります。
  4. ひたすら翻訳.
    この際に、下のような訳文の書式が決まっています。
  5. JF-ML にドラフトを流す。
    ドラフトを流す際には、
    Subject: [CH:DRAFT] CONFIG_XXXXXXX CONFIG_XXXXXXX 2.2.2
    という風に、翻訳元のバージョンまで一目でわかるようにしてください。 同バージョンの複数項目に対するドラフトは一通のメールにまとめていただくと助かります。
    ただし、Configure.help 翻訳作業に関しては、このドラフト段階はスキップすることが 認められています。 いきなり次の決定稿を流す段階に進んでもかまいません。
  6. JF-ML に決定稿を流す。
    決定稿(リリース版)を流す際には、
    Subject: [CH:FINAL] CONFIG_XXXXXXX CONFIG_XXXXXXX 2.2.2
    という風に、翻訳元のバージョンまで一目でわかるようにしてください。 同バージョンの複数項目に対するリリース版は一通のメールにまとめていただくと助かります。 また、登録の際には訳者の名前とメールアドレスを リポジトリ内部のファイルに記録することになるので、 それについても明記をおねがいします。
  7. Committer が Git リポジトリに登録
これで作業は終りです。