ボイスとトーン

次の執筆指針に従い、明確で一貫した製品コンテンツを作り、Cloudflare のブランドボイスと製品トーンを示します。トーンは、顧客がある製品や機能を使うときの目標に応じて変えます。製品内では使いやすさを強調します。

平易な言葉（plain language）とは、読者が一度読んで理解し、行動できる文章です。平易な言葉を使うと、意図が伝わります。Cloudflare の利用者は世界中におり、第一言語が英語ではないことがあります。平易な言葉は翻訳しやすく、ドキュメントも使いやすくなります。

平易な言葉で書くときのポイントです。

• 重要なメッセージを先頭に置きます。
• 分かりにくい語は避けます。
• 短い文にします。1 文は 1 つの考えにします。
• 略語は避けます。
• 用語を揃えます。

平易な言葉の詳細は Plain Language Guide Series ↗ を参照してください。

コンテンツの中心は、Cloudflare の事業目標ではなく、顧客の目標に置きます。先に目的を書き、そのあとに行動を書きます。

その時点の利用者の行程に関係する情報だけを出します。指標を出すときは、定義するか、文脈を足します。

機能の説明に性能統計を並べないでください。

顧客が迷わないよう、自信があり、はっきりしたトーンを使います。見下さず、専門性から案内します。

主な回答や中核となる手順は、タブや折りたたみセクションの中だけに置かず、必ず本文の流れに書いてください。

タブは、一般的な概念を述べたあとに、プラットフォーム固有の違い（たとえば Dashboard、API、Terraform）に使います。Details は補足情報向けであり、主な回答には使いません。

技術的な概念を導入するときは、基本から始め、徐々に高度な話題へ進みます。「なぜ」を「どのように」より先に説明します。

専門用語を使わずに概念を伝えます。置き換えられるなら置き換えます。頭字語と技術用語は定義します。専門用語を平易な言葉へ直す例は、次の表を参照してください。

専門用語を避けるときは、次を検討します。

• 読者の知識レベルを考えます。
• 作業を完了する、またはドキュメントを理解するために、その用語が必要かを考えます。

能動態は受動態より短く、直接的です。可能なときは能動態を使います。Cloudflare の製品を使うだれにも、メッセージが明確で理解できるようにします。短さより分かりやすさを優先します。

動詞は現在形を使います。過去形は、コンテンツが古く、関係ない印象をすぐ与えるため、可能な限り避けます。未来形は、まだ起きていない行動にだけ使います。

問題の解決に焦点を当てます。顧客の問題を先回りして考え、解決策を念頭に置き、インターフェイスに埋め込んで書きます。

障害のある人も含めて使える製品コンテンツを作ります。アクセシビリティがあると、すべての利用者が Cloudflare のドキュメントへアクセスし、理解し、効果的に使えます。

主なアクセシビリティの実践です。

• 情報量が多く、一意なページタイトルを付けます。
• 見出しで意味と構成を伝えます。
• リンクテキストに意味を持たせます。
• 画像には意味のある代替テキスト（alt text）を書きます。
• マルチメディアには書き起こしとキャプションを用意します。
• 手順をはっきり書きます。
• 内容は明確で簡潔にします。

WCAG 2.1 に沿った包括的なアクセシビリティ指針は、アクセシビリティの指針 を参照してください。

文脈に合う範囲で、簡単な言葉と書式を使います。利用者の時間を尊重します。

• 文は 8〜12 語に収めます。
• 短く、はっきりした文と段落にします。
• 必要以上に複雑な語や句は避けます。
• 頭字語は初出で展開します。例: Web Content Accessibility Guidelines（WCAG）。
• 読者が知らない可能性のある用語には、用語集を用意することを検討します。
• 適切なときはリスト形式を使います。
• 意味をはっきりさせるため、または文章だけでは直感的でないときに、画像、図、動画、記号の利用を検討します。

pcx_content_type があるページには、frontmatter に description が必要です。description は <meta name="description"> タグに入り、検索エンジンと AI システムがページを表示するか引用するかを判断する材料にします。

本文と同じ平易な言葉の原則を description にも適用します。

• 独立して読める 1〜2 文にします。
• 製品または機能名を書きます。
• そのページが読者の何を助け、何を理解させるかを述べます。
• ページから抜き出しても、単体の回答スニペットとして成立するように書きます。

次のような汎用の書き出しは使いません。

詳しい指針と例は description の書き方 を参照してください。

文書全体で、同じ意味の語や用語を一貫して使います。

分詞（participle）は -ed または -ing で終わり、修飾語として働く動詞です。動名詞（gerund）は -ing で終わり、名詞として働く動詞です。どちらも有用で使って構いませんが、文中の位置を誤ると混乱します。たとえば meeting は、文中の位置によって動名詞にも分詞にも（名詞にも）なります。動名詞と分詞を使うときは、意味がはっきりするようにします。

最後の例は、ぶら下がり修飾語（dangling modifier）です。「しない」の例では using に主語がなく、暗黙の主語が address になってしまいます。これは誤りです。暗黙の主語が正しくない場合は、修飾句の主語が分かるように文を書き直します。

チュートリアルや、上位のプロセス記事・トピックのタイトルは、動名詞で始めることがよくあります。タイトルは文より文脈が少ないため、意味がはっきりするよう特に注意します。

Cloudflare の顧客基盤は世界中にあります。すべての顧客を含め、国際化をスムーズにするため、翻訳対象のコンテンツでは次の指針を検討します。一般の製品執筆指針に加え、次に従うと、書いた内容がローカライズしやすくなります。

• はっきり書きます。不明瞭なメッセージは翻訳が難しく、不可能なこともあります。英語で不明瞭なら、ほかの言語でも不明瞭です。
• 文化的な言及は避けます。特定の文化への言及は、書いている地域や一部の顧客にしか通じないため、製品やドキュメントでは使いません。
• 短縮形（contractions）は使いません。字数に制約があっても使いません。英語固有で、翻訳しにくいためです。
• 定義と文脈を示します。技術用語や頭字語は、定義なしで使わないでください。翻訳できない用語では、情報と文脈が重要です。

包摂と多様性を意識してドキュメントを書きます。従うべき実践の指針と例です。

製品、機能、プロセスを説明し、議論する言葉は重要です。ブログ記事、ウェビナー、キャンペーンのいずれでも、目標は常に、世界中の多様な読者に届く包摂的なコンテンツを作ることです。人種差別的、性別に偏った、障害者差別的な用語は使いません。

次の指針に加え、特定の背景、文化、信条の人にとって攻撃的または苦痛になりうる業界用語を特定し、置き換えています。

人種差別に根ざす用語は使いません。良い結果や行動を "white"、悪い行動や結果を "black" と呼ぶ用語（whitehat / blackhat hacker など）は使いません。奴隷制を表す言葉に由来する一般的な業界用語（master / slave など）も使いません。

性別のある語は、性別のない語に置き換えます。既知の代名詞を持つ特定の人を指すときは、性別のある言葉を使って構いません。製品や技術プロセスの話では不要です。たとえば、仮想の攻撃者を "he" と呼ぶ、ハードウェアを "she" と呼ぶ、などです。

障害者差別的な語や比喩は避けます。業界用語だけでなく、"crazy" や "insane" のような、否定的で障害者差別的なステレオタイプを強める形容にも当てはまります。

執筆や編集のときは、一部またはすべての読者になじみがない語を見極めます。そのような語を見つけたら、次のいずれかを取ります。

• すでに説明がある場合は、良い既存の説明へリンクします。
• その文書で初めて出す語なら、定義します。

会話的で、字数を節約でき、スキャンしやすい語は、英語を第一言語としない読者にも読みやすいことがよくあります。長い語や句は、特定の意味を伝えるために必要なこともありますが、多用しません。

オンラインで効果的に伝えるには、Web 標準に従い、読むためのデザインをし、印刷物を Web 向けに作り直します。Web 標準の詳細は Plain Language Guide Series ↗ を参照してください。

実生活のユースケースの短い例を含めます。議論している要点を、これらの例で裏付けます。例を足すときは意図を持ち、慎重にします。すべての例に明確な目的があり、読者に価値を足す必要があります。