スタイルガイド

スタイルガイド

著者向けガイドライン

この節では Live マニュアル向けの技術的文書を記述する際に一般的に考慮すべき事項を扱います。言語特性と推奨手順に分かれています。

注意: 著者はまず{この文書への貢献}#how-to-contribute を読んでください

言語特性

●  平易な英語を使う

読み手は英語が母国語ではない人の割合が高いことに留意してください。そのため、一般的規則として短く有意な文章を使い、引き続いて終止符を打ってください。

これは単純で幼稚な書き方をするように言っているわけではありません。英語が母国語ではない人にとって理解しにくい複雑な従属文にすることを可能な限り避けましょうという提案です。

●  英語の方言

最も広く使われている英語の方言はイギリス英語とアメリカ英語なので、ほとんどの著者が非常に高い率でこのどちらかを使っています。共同作業環境下で理想的なのは「国際英語」ですが、既存の全ての方言からどれを使うのが最善なのか決定するのは不可能とは言いませんが非常に困難です。

誤解を生まずに複数の方言を混在させることもできるとは思いますが、一般論として一貫性を持たせるようにすべきで、また、イギリス英語やアメリカ英語、その他の英語の方言からどれを使うか自分の裁量で決める前に、他の人がどのように書いているのかを調べてそれを真似るようにしてください。

●  バランス良く

偏見を持たないようにしてください。Live マニュアルに全く関係のない思想への言及を引用することは避けてください。技術的文献は可能な限り中立であるべきです。科学的文献では中立こそが自然です。

●  政治的に正しく

性差を表す言葉を可能な限り避けるようにしてください。個人の第三者を持ち出す必要がある場合は「he (彼)」や「she (彼女)」、あるいは「s/he や s(he) 彼(女)」などと複雑にするよりも「they (彼ら)」を使うのが好ましいです。

●  簡潔に

要点を直接述べ、回りくどい表現を使わないようにしてください。必要な情報は十分に提示ながらも、必要以上の余計な情報を提示するのはやめてください。これは不要な詳細を説明しないようにということです。読み手には理解力があります。読み手の側にいくらか前提知識があることを仮定してください。

●  翻訳作業を最小限に

書かれたものは他の複数の言語に翻訳されることになるということに留意してください。これは無意味あるいは冗長な情報を追加するとその分余計な作業をする人が出てくるということを意味します。

●  一貫性を

前にも提案しましたが、共同作業の文書を標準化して全体を完全に統一することはほぼ不可能です。しかし、文書を書く際に全体を通して他の著者と一貫した書き方をすることを歓迎します。

●  結束性を

必要なだけ文脈形成句を使い、文章に結束性を持たせて明確にしてください (文脈形成句は接続語句等の言語標識です)。

●  記述的に

標準的な「changelog」形式で文を単に羅列するよりも段落を使って要点を説明する方が好ましいです。描写してください! 読み手はそれを歓迎するでしょう。

●  辞書

英語で特定の概念を表現する方法がわからないときは辞書や百科事典でその語の意味を調べてください。ただし、辞書は最高の友ですが正しい使い方を知らなければ最悪の敵にもなることに留意してください。

英語には最大の語彙が存在する言語の一つです (100万語以上)。この語の多くは他の言語から取り入れられたものです。単語の意味を二カ国語の辞書で調べる際、英語が母国語ではない人は母国語の言葉により似ているものを選択する傾向があります。このことにより、英語ではあまり自然に聞こえない、過度に形式ばった文体になりがちです。

原則として、ある概念が複数の異なる同義語により表現できるとき、辞書で最初に提示された語を選択するのが良い判断となるでしょう。疑問がある場合はゲルマン起源の語 (通常単音節の語) を選択すると多くの場合正しいとなります。この2つの技ではどちらかというとくだけた表現になるかもしれないという点には注意が必要ですが、少なくとも広く使われていて通常受け入れられる語を選択することになります。

共起辞書の利用を勧めます。通常合わせて利用する語がわかるようになると極めて役に立ちます。

繰り返しますが、他の人の作業から学ぶことが最良の実践です。検索エンジンを使って他の著者が特定の表現をどのように使っているか確認することは大きな手助けとなるでしょう。

●  空似言葉や熟語その他の慣習的な表現

空似言葉に気をつけてください。外国語の熟練度を問わず、2つの言語で同じように見える語だけれどもその意味や使い方が全く異なる「空似言葉」という罠にはまることがあることは避けられません。

熟語は可能な限り避けてください。「熟語」は個々の語が持っていた意味とは完全に異なる意味を表すことがあります。熟語は英語が母国語の人でさえ理解しにくいこともあります!

●  俗語や省略、短縮表現等は避けましょう

平易な、日常的な英語の使用を勧めるとはいっても、技術的文献は言語を正式に記録する類のものです。

俗語や通常使わない解釈困難な省略表現、特に母国語での表現を模倣するような短縮表現は避けてください。IRCや、家族や仲間内で使うような特有の表現での記述はしないでください。

手順

●  書く前にテストを

著者が Live マニュアルに追加する前に例をテストして、全て確実に説明通りに動作するようにすることは重要です。きれいな chroot やVM環境でのテストが良い起点となるでしょう。他に、それから異なるハードウェアを使っている異なるマシンでテストを実施し、起きるであろう問題を発見することができれば理想でしょう。

●  例

例示するときはできるだけ具体的にするようにしてください。例は結局例でしかありませんから。

抽象的な表現で読み手を混乱させるよりも、特定の状況でのみ適用できるような書き方をする方がより良いことはよくあります。この場合は提示した例の効果を簡単に説明することもできます。

使い方を誤ればデータ消失や類似の望ましくない影響を及ぼす可能性のある、潜在的に危険なコマンド類の使用を例示する場合等、例外がいくらかあります。この場合は起こりうる副作用について十分な説明を提供すべきです。

●  外部リンク

外部サイトへのリンクは、そのサイトにある情報が特別な点を理解するために決定的な効果が期待できる場合にのみ利用すべきです。その場合でも、外部サイトへのリンクは可能な限り少なくしてください。インターネット上のリンクはその内容がほとんどが変更される可能性があるもので、その結果機能しないリンクができたり、論拠を不完全な状態にしてしまうことになります。

他に、インターネットに接続せずにそのマニュアルを読んでいる人にはそのリンクを追う機会がありません。

●  商標の主張やマニュアルの公開にあたって採用したライセンスに違反するものは避ける

商標の主張は可能な限り避けてください。記述した文書は他の下流のプロジェクトで使うことになるかもしれないことに留意してください。つまり、ある種の特定の内容を追加することは事態を複雑にすることになります。

live-manual は GNU GPL の条件下で使用を許可しています。これには、合わせて公開する (著作権のある画像やロゴを含むあらゆる種類の) 内容の配布物に適用する意味合いがいくつかあります。

●  まず草稿を書き、改訂、変更して改善し、必要なら作り直す

- 案を引き出しましょう! まず論理的に順を追って考えを整理する必要があります。

- 頭の中で何とか形ができたら最初の草稿を書きます。

- 文法や書式、つづりを直します。リリースの正しい名前は ${testing} や sid で、これをコード名として参照するときは大文字にすべきではないことに留意してください。「spell」ターゲットを使って、つまりmake spellでつづりの誤りがないか確認できます。

- 記述を改善し、必要な部分があれば書き直します。

●  章

章や副題には慣習的な番号の付け方をしてください。例えば 1、1.1、1.1.1、1.1.2 ... 1.2、1.2.1、1.2.2 ... 2、2.1 ... などというようにです。以下のマークアップを見てください。

説明するのに一連の手順や段階を列挙する必要がある場合は、First (最初に)、second (2つ目に)、third (3つ目に) ... というように序数を使ったり、First (最初に)、Then (それから)、After that (その後)、Finally (最後に)、... あるいは箇条書きすることもできます。

●  マークアップ

大事なことを言い忘れましたが、live-manual では SiSU を使ってテキストファイルを処理し、複数の形式の出力を生成しています。{SiSU マニュアル}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html を眺めてそのマークアップ方法をよく理解することを勧めます。代わりに

 $ sisu --help markup  

と入力する方法もあります。マークアップをいくらか例示してみます。有用だということはわかるかもしれません。

- 文字列の強調/太字:

*{foo}* または !{foo}!  

は「foo または foo」となります。これは特定のキーワードを強調するのに使います。

- 斜体:

/{foo}/  

は foo となります。これは例えば Debian パッケージの名前に使います。

- 等幅:

#{foo}#  

は foo となります。これは例えばコマンドの名前に使います。また、キーワードやパスのようなものの一部を強調するのにも使います。

- コードブロック:

 code{

  $ foo
  # bar

 }code  

は

 $ foo
 # bar  

となります。タグの開始には code{ を、終了には }code を使います。コードの各行には先頭に空白が必要だということを必ず覚えておいてください。

翻訳者向けガイドライン

この節では Live マニュアルの内容を翻訳する際に一般的に考慮すべき事項を扱います。

一般的な推奨事項として、翻訳者は自分の言語に適用される翻訳規則を既に読んで理解しておくべきです。通常、翻訳用のグループやメーリングリストが Debian の品質標準に合致する翻訳物を作成する方法についての情報を提供しています。

注意: 翻訳者は{この文書への貢献}#how-to-contribute も読むべきです。特に{翻訳}#translation 節を

翻訳の手がかり

●  コメント

翻訳者の役割は元の著者により書かれた語や文、段落、そして文章の意味を可能な限り忠実に目標の言語で伝えることです。

そのため、個人的なコメントや自分の余計な情報の追加は控えるべきです。同一の文書について作業している他の翻訳者に向けてコメントを追加したい場合はそのために用意されている場があります。これは po ファイルの番号記号 # に続く文字列のヘッダです。ほとんどの視覚的な翻訳用プログラムで自動的にこれをコメントの種類に属するものとして処理します。

●  TN, Translator's Note (翻訳者によるメモ)

完全に受け入れられるとはいえ、翻訳済みテキストの括弧「()」内に語や表現を含めることは、ややこしい語や表現の意味を読み手にとってより明確にする場合にのみ行ってください。翻訳者は括弧内に「(訳注)」等と記載して、その追記が翻訳者によるものであることを明確にすべきです。

●  非人称の文を

英語で書かれた文書は「you」を非人称として幅広く使います。他の言語にはこの特徴を共有しないものもあります。このことで、元の文が読み手に対して直接呼びかけているかのような誤った印象を実際にはそうではないのに与えてしまうかもしれません。翻訳者はこの点に注意して、可能な限り正確に自分の言語に反映する必要があります。

●  空似言葉

前に説明した「空似言葉」の罠は特に翻訳者に当てはまります。疑いがあれば、その疑わしい空似言葉の意味を再点検してください。

●  マークアップ

最初はpotファイル、後にはpoファイルについて作業する翻訳者は多数のマークアップ機能を文字列に確認できるでしょう。文は翻訳できるものである限り翻訳できますが、それが元の英語版と全く同一のマークアップを採用しているということは極めて重要です。

●  コードブロック

コードブロックは通常翻訳できませんが、翻訳にそれを含めることが、翻訳率 100% を達成する唯一の方法です。コードが変更されると翻訳者による介入が必要となるため最初は余計な作業になりますが、長期的に見るとこれが .po ファイルの整合性を確認したときに何が既に翻訳済みで何が未翻訳なのか識別する最善の方法です。

●  改行

翻訳文には元の文と全く同じだけの改行が必要です。元のファイルに改行があるときは注意して「Enter」キーを押すか\nを打ち込んでください。改行は例えばコードブロック中でよく使われます。

勘違いしないでください。これは翻訳文を英語版と同一の長さにする必要がある、ということではありません。それはほぼ不可能です。

●  翻訳できない、してはいけない文字列

翻訳者が決して翻訳すべきでないもの:

- リリースのコード名 (小文字で書くべき)

- プログラムの名前

- 例示するコマンド

- メタ情報 (前後にコロンが置かれることが多い :メタ情報:)

- リンク

- パス