ハクソク

世界を動かす技術を、日本語で。

レッドハット技術文書スタイルガイド

304日前原文(stylepedia.net)

概要

  • Red Hat Style Guide の目的と基本方針を解説
  • 文法・語法・句読点 の重要なガイドラインを要約
  • アクティブボイス や 一致 などの具体的な用法例を提示
  • 数えられる名詞 や 所有格 の正しい使い方を説明
  • 文の構造 や 関係代名詞 の選択基準を整理

Red Hat Style Guideの目的

  • Red Hat Style Guide は、著者が 明確かつ一貫性のある情報伝達 を行うための指針
  • 多様な読者層 （エンドユーザーからエキスパートまで）を想定したドキュメント作成
  • 正確性 と 一貫性 の確保
  • 可読性 （Flesch-Kincaidスコア60-70）と 理解しやすさ （Gunning Fog index 9-12）の基準
  • ユーザー中心 の情報提供、読者を見下さず、スキルを決めつけない配慮

可読性基準

  • 技術文書は 対象読者にとって読みやすい ことが必須
  • 最低でも中学2年生程度の読解力 を想定
  • Flesch-Kincaid ・ Gunning Fog index で評価
  • Gunning Fog index 9-12 を目標

文法ガイドライン

  • The Chicago Manual of Style, 17th Edition を参照
  • ここでは よくある文法事項 を重点解説

アクティブボイス（能動態）

  • 能動態 を基本とし、例：「Type ... to start Linuxconf」
  • 受動態 も状況により使用可（例：重要語句を前面に出す場合やリリースノート等）
  • 能動態 は 簡潔 で 読みやすい 文書作成に有効
  • 例：
    • 能動態 ：「Dutch hosting provider Oxilion launches public cloud service based on Red Hat Enterprise Virtualization.」
    • 受動態 ：「Public cloud service based on Red Hat Enterprise Virtualization launched by Dutch hosting provider Oxilion.」

一致（Agreement）

  • 文法的一致 は 数・性 で発生
  • 主語-動詞一致 は基本的知識
  • 代名詞-先行詞一致 は注意が必要
代名詞-先行詞一致
  • 単数名詞 には 単数代名詞、 複数名詞 には 複数代名詞
    • 例：「The CD spins in its caddy.」「The developers checked their work.」
  • 集合名詞 は文脈により 単数/複数代名詞 を使い分け
    • 例：「Microsoft seems second to none in its marketing skills.」「The developers were asked for their preferences.」

数えられる名詞（Countable Nouns）

  • 不可算名詞 には「less」「amount」
    • 例：「less memory」「the required amount of memory」
  • 可算名詞 には「fewer」「number」
    • 例：「fewer opportunities」「exact number of words」
  • 改善例 ：
    • 誤：「providing less opportunities」→ 正：「providing fewer opportunities」
    • 誤：「exact amount of words」→ 正：「exact number of words」

所有格（Possessives）

  • 所有格 は「誰か/何かに属する」ことを示す
  • 製品名や略語 には所有格を使わない
    • 誤：「Red Hat OpenShift's Logging operator」→ 正：「The Red Hat OpenShift Logging operator」
    • 誤：「NASA's documentation」→ 正：「NASA documentation」
  • Red Hat 社名自体や人名・無生物には使用可
    • 例：「Red Hat's diversity, equity, and inclusion efforts」「Eddie Jaoude's YouTube channel」

関係代名詞の使い分け（Who, Whom, That, Which）

  • who/whom ：人に対して使用
  • that/which ：物や概念に対して使用
  • who ：主語となる人
  • whom ：主語以外の人
  • which ：物に対する関係代名詞
  • that ：物に対する制限用法
  • 例：
    • 「The jewel case, which previously held the CD, was broken recently.」
    • 「The CD that I received for my birthday is defective.」
    • 「Edward C. Bailey, who wrote "Maximum RPM", ...」
    • 「The company that published "Maximum RPM" was ...」
    • 「Who ate all the cereal?」「To whom should I address the letter?」

文の構造（Sentence Structure）

  • 一文一義 を基本とし、 40語以内 を推奨
  • 情報過多な長文 は避ける
  • 改善例 ：
    • 誤：一文に複数の情報を詰め込む
    • 正：短文で分割し、要点ごとに整理

論点転換時の新セクション例

句読点やその他の文法事項

  • コロン・セミコロン・カンマ などの用法
  • リスト内や表内での句読点 の使い方
  • 特殊文字や記号 の名称・参照方法
  • 省略形・略語・特別な記号 の正しい使い方
  • 会社名・製品名・ブランド名 の表記ルール
  • 非改行スペースやバージョン番号 の使い方
  • 引用・参考文献の記載方法

このガイドを参照し、 一貫性・明瞭性・可読性 を常に意識した技術文書作成を心がけること。

Hackerたちの意見

うわー、これは本当に素晴らしいガイドだね。結構長いけど、長さの理由は内容の幅広さであって、冗長だからじゃないと思う（私見だけど）。特に、明確な説明とたくさんの例があって、概念を具体的に理解するのに役立つのがいいね。レッドハットで働いてない人にも、かなり役立つ内容だと思うよ。

しっかりしてるね。ほとんどの技術文書（TW）のスタイルガイドに対する不満は、ベストプラクティスと慣習が混ざってることだね（これもそうだけど）。* 「ベストプラクティス」：文書の質を実際に向上させる要素。通常、実験データや圧倒的な合意に裏付けられてる。* 「慣習」：文書の質を明確に向上させるわけではない恣意的な決定。ただ、一貫性を高めるから、一貫性のある文書は使いやすい。みんながこの共通理解を持ってると、TWスタイルガイドの会話はすごくスムーズに進むよ。

└

うーん、あんまり良い点が見えないな。好きな例とかある？

└

僕はこの両方の立場を経験してきたけど、執筆の対象によるって気づいたんだ。これはレッドハットの著者が様々なユーザー向けに雑多なドキュメントを書くためのものみたいだね。そこでの一貫性は重要で、レッドハットがメッセージに一貫性を持たせるためには、単一のユーザーが多くの著者からの資料を読むことがあるから。小さなことがバラバラだと雑に見えちゃうよね。多くの場合、ユーザーは一人の作家からのコミュニケーションを受け取ることが多い。これはコンサルティングの契約だったり、小さな会社だったり、いろんなケースがあるよね。そのユーザーたちはおそらく自分たちのスタイルを一貫させるから、小さなことに関してはそれほど具体的である必要はないんだ。その場合、ガイドは誰かの文書の明らかな粗を取り除いて、実際に情報を伝えているか確認するためのものだね。

ほとんどの部分はかなり良さそうだね！ただ、文法セクションの一部がちょっと引っかかる。そこには「能動態を受動態より好む」といったベストプラクティスと、主語と動詞の一致に関する基本的なルールが混ざってる。前者はスタイルガイドで期待する内容だけど、後者は…うーん、高校の英語をパスするための基本的な要件として期待するものかな？技術ライターに求められる流暢さのレベルを考えると、基本的な文法ルールはしっかり理解していて、明示的に書かれる必要はない気がする。

└

うん、私も同じこと考えてた。細かいところに迷ってるね。

└

非英語圏の人が多い業界では、両方あるのは理解できるよ。アドバイスを分けた方がいいと思う。意見や組織特有のアドバイスは一つのセクションに、文法は別のセクションに。能動態を使うことや、製品名に所有格を使うのはスタイルの話。「Who vs. Whom」は文法の話だね。

└

主語と動詞の一致に関する基本的なルールと混ざってる (...) [それは] 高校の英語をパスするための基本的な要件として期待するものだと思うけど、これはあなたの方で例が不適切だったんじゃないかな。ガイドには以下のように明記されてるよ：> 一致には二つの形式がある：主語と動詞の一致、代名詞と先行詞の一致。主語と動詞の一致はかなり基本的なもので、ここでは議論されていない。とはいえ、時には（しばしば？）技術文書は実際には技術ライターでない人が書くこともある。その中には英語以外の母国語を持つ人も多いし、たくさんの高校では英語の授業をパスするのはそれほど高いハードルじゃない。特に、大勢の人を不合格にするのは現実的じゃないからね。人に言語を学ばせるのにも限界があるよ。

└

技術文書において、能動態が常にベストとは限らないよ。手順を説明する際には、受動態を交えた方が自然な読みやすさを保てることもあるし、命令形が続くと堅苦しくなっちゃうこともある。学校で教わる一般的な英語の文体が普遍的に適用できるわけじゃないからね。

└

私は、かなり読み書きができるネイティブの英語話者でも、最も単純な文以外では主語と動詞の一致で時々間違えることがあると思ってる。 例えば、「サーバーまでの距離は、レイテンシに影響を与える要因の一つです。」と読むのは驚きじゃない。

私の英語が下手だからかもしれないけど、これらの例はどちらもひどく読みにくいよね。

例えば、「開発者センター、参考資料やその他のリソースのためのサイトが、OpenShiftのウェブサイトに紹介されました。」は、次の部分を読まなくても、これがより良いとは思えなかった。 「参考資料やその他のリソースのためのサイト」という挿入があるせいで、この文は本当に追いにくい。 「OpenShiftのウェブサイトは、参考資料やその他のリソースのためのサイトである開発者センターを紹介します。」 ここでは、受動態の方が良い。なぜなら、重要な問題（「開発者センター」）が文の主語になっているから。 この文は別の理由でもおかしいと思う。ウェブサイトが何かを「紹介する」ことはないから。ウェブサイトの所有者がするかもしれないけどね。それに、「参考資料」じゃなくて「参考資料たち」と言うべきだと思う。

└

方言かもしれないけど、アメリカ英語では「reference material」は普通に聞こえると思うよ。 （この文脈では「material」が不可算名詞か集合名詞か何かなんじゃないかな）

└

最初の例の文構造（「主語、長い余談、結論」）は、ドイツ語ではとても一般的だよね（私がドイツ語を読むときの大きなイライラの一つ）。 だから、著者はその背景があるのかも？

└

君の意見に賛成だな、これらの例はちょっと不自然に感じる。>「これは別の理由でおかしい：ウェブサイトは…物事を紹介しない。」彼らが「紹介する」という言葉を使ってるのは確かに不自然だけど、一般的にはウェブサイトが何かを「紹介する」と言っても問題ないよ。例えば、ホムスターランナーのウェブサイトはストロングバッドを世に知らしめたし、アクションコミックス#1はスーパーマンを紹介した。アクションコミックス#1の作者がスーパーマンを紹介したとは言わないよね。

これとIBM、DEC、Sun、Apple（初期のMacOS）、Microsoftなどの他のスタイルガイドとの比較はある？ これらはすべて社内印刷所を持っていたから、内部使用のために一貫性を提供するためのスタイルガイドがあったはずだよね。

ここの部分は素晴らしい。私は2年生と3年生の法学生向けに契約書作成のコースを教えているけど、あまり文章が上手じゃない学生もいる。 彼らの作品にマークを付けるとき、RHガイドの特定のポイントへのリンクを提供できる。 ただ、いくつかの部分はあまり良くない。例：

例[:] リモートユーザーは、自分のローカルマシンに認証することでネットワークリソースに接続できます。 改善[:] リモートユーザーは、自分のローカルマシンに認証することでネットワークリソースに接続できます。 「simply」を省くことで文が改善されるとは全く明らかではない。 圧縮された情報が失われることになる。つまり、ローカル認証の代替手段がもっと複雑かもしれないという暗示がある。 この暗示は、読む人や書き手にとって重要かもしれない。

└

私の経験では、技術系の人は「simply」を使いすぎる傾向がある。 この言葉は通常、取り除いた方がいいと思う。

良い技術文書は、良いインテリアデザインに似ていると思う。 私の兄はインテリアデザイナーで、ホテルの仕事をたくさんしている。 彼曰く、インテリアデザイナーとしては、悪くデザインした場合にしか人々はあなたの仕事に気づかない。 ちゃんとデザインされたホテルの部屋を使ってもあまり気にしないけど、レイアウトが悪いなどの問題があると、何かおかしいと感じる。 もし読者が技術記事に対して意見を持たず、期待していた情報を得られたなら、それはおそらく良く書かれている。 私が技術文書を書くときは、情報をできるだけ効果的かつ冷静に提供する妨げになるものは避けるようにしている。

└

それは信頼できる技術文書にはいいレシピかもしれないけど、素晴らしいものとは言えないかも。僕のお気に入りの作家たち、ドナルド・クヌースやレオ・ブロディ、マーシャル・カーク・マクキューシック、ハーレイ・ハーン、ジェフ・ダンテマン、ビージ、ニルス・ホルム、他にもたくさんいるけど、彼らはすごく個性的で魅力的な文を書いてる。冷たくて感情がない感じは全然しないよ。あ、デニス・ユリチェフもね。

└

会計やセキュリティ、QAで仕事が悪いと、みんなに気づかれるよ。

かなりいい感じだね。これを執筆の参考リストに加えるよ。オーストラリアのスタイルマニュアルとDivioドキュメンテーションシステムを、技術文書やユーザードキュメントの基盤としてよく使ってるんだ。

特にこのセクションがビジネス用語を指摘しているのを見るのは満足感があるね： https://stylepedia.net/style/#avoiding-confusing-language 例えば、ベスト・オブ・ブリードのジャーゴン。正確に言いたいことを言おう、例えば「そのクラスで最高の製品」や「そのタイプで最高の製品」とか。他の選択肢には、ベスト、最も優れた、最先端、最適などがあるよ。カテゴリーは通常暗黙の了解だね。データなしでの最上級の使用には注意が必要だよ。bleeding edgeは使わないで。boil the oceanも使わないで。正確に言いたいことを述べよう、「範囲を大幅に増やす」とかね。

└

面白いことに、そういう用語を普段使っている人にとっては、「正確に言いたいことを述べている」んだよね。つまり、「範囲を大幅に増やす」という言葉自体はギリシャ語から来ていて、その核心的な意味は「見る」や「眺める」なんだ。プロジェクトがカバーすべきものの規模や量を意味することもみんなが知っているから、理解できるんだと思う。（プロジェクトが目標の数や大きさが増えるにつれて「見渡す」というメタファーがあるのかも。）だから「正確に言いたいことを述べるべき」ではなくて、「できるだけ広く使われている言葉で言いたいことを述べるべき」って感じだね。

例文「Red Hatは時期が来るまでアップグレードをリリースしない。」は「it's」の方がいいかも。

└

いや、ここを見てみて：https://www.merriam-webster.com/dictionary/ahead%20of%20one'...