docs-style-guide

ドキュメントスタイルガイドの適用と徹底

製品ドキュメントやチュートリアルを作成またはレビューする際に、ライティングスタイルガイドを適用し、徹底します。ガイド全文は、このスキルに ./reference/ の下で同梱されています。ルールを適用または引用する前に、該当するファイルを読み、記載内容を正としてください。

このセッションで読み込んでいないルールを引用、出典として明記、またはリンクしてはいけません。また、ルール、Do／Don't の例、参照先のパスを創作してはいけません。ファイルを読んでいない場合は、先に読んでください。そうでなければ何も述べないでください。

目的

一貫したスタイルと語調で文章を書くことで、ブランドを強く、活気のあるものにできます。スタイルガイドは、次の目標を反映しています。

• 英語を母語としない人にとって読みやすい文章にします。
• 疲れているオペレーターにとって読みやすい文章にします。
• コンテンツの作成者にとって使いやすい文章にします。
• 複数の製品で使いやすい文章にします。

基本原則

• 印刷物でよく見かける表現であっても、比喩、直喩、その他の修辞表現は使いません。
• 短い言葉で済む場合、長い言葉は使いません。
• 削れる言葉があれば、必ず削ります。
• 能動態を使える場合、受動態は使いません。
• 日常的な英語に言い換えられる場合、外国語の表現、専門用語、または業界用語は使いません。
• ガイドラインを守ることで、かえって悪影響が生じる場合は、そのルールを破ります。

コンテンツの範囲

ガイドラインを適用する前に、ルールの content sets フィールドを確認し、作業対象のコンテンツに適用されるかどうかを確かめてください。このフィールドには、次のコンテンツタイプが1つ以上記載されています。

• documentation — 現在の機能を説明する、製品のリファレンスドキュメントおよび概念ドキュメント。
• tutorials — 特定の結果を得るための一連のタスクを読者に案内する、段階的な学習コンテンツ。

執筆またはレビューを始める前に、該当するコンテンツセットを判断してください。概念ページの最後に手順に沿った解説がある場合など、コンテンツが両方のセットの特徴を持つ場合は、それぞれのルールを該当するコンテンツ部分に適用してください。分類できない場合は、documentation のルールを適用し、テクニカルライターに相談してください。現在のコンテンツセットが記載されていないルールは適用しないでください。

ワークフロー

1. コンテンツセットを特定します（documentation または tutorials）。対象コンテンツを確認してください。
2. 関連するガイダンスを選びます。 以下の参照マップに記載されたトピック別ファイルのうち、対象コンテンツに該当するものを使用してください。
3. 適用または引用する前に、ルールファイルを読みます。 ガイダンスや例が正確であることを確認してください。
4. 適用または報告します。
   • 執筆する場合は、該当するルールに準拠したコンテンツを作成します。
   • レビューする場合は、違反箇所ごとに、該当する具体的なルール、そのルールファイルへのリンク、ガイドに記載された Do／Don't の修正例または例を報告します。
5. コンテンツセットを尊重します。 各ルールが対象とするコンテンツセットを確認し、現在のコンテンツセットが含まれていないルールは適用しません。

確認

レビューのみを行う場合は、作業を止めずに違反箇所を報告します。既存のファイルに編集を加える前に、予定している変更内容を確認し、正確に判断するために必要なコンテキスト（コンテンツセットなど）があれば推測せずに尋ねてください。

参照マップ

• 一般的な文章作成ガイドライン（./reference/general/）：
  • active-voice.md — 能動態
  • content-organization.md — コンテンツの構成
  • fonts-and-formats.md — フォントと書式
  • grammar.md — 文法と句読点
  • language.md — 言葉遣いと語句の選択
  • links.md — リンク
  • point-of-view.md — 視点
  • tense-and-time.md — 時制と時間
  • titles-and-headings.md — タイトルと見出し
• コードブロックとコンソール（./reference/codeblocks-and-consoles/）：
  • organization.md — コンテンツの構成
  • fonts-and-formats.md — フォントと書式
  • language.md — 言葉遣いと語句の選択
• reference/ui-components.md — UI コンポーネント。
• 数字、日付、時刻（./reference/numbers-dates-time/）：
  • dates-and-time.md — 日付と時刻
  • format-numbers.md — 数値の書式
  • words-as-numbers.md — 数字を表す言葉
• Markdown の規約（./reference/markdown/）：
  • fonts-and-formats.md — フォントと書式
  • headings.md — 見出し

避けるべきパターン

• ルールに記載されていないコンテンツの種類に、そのルールを適用する。
• 読み込んでいないルールを引用または言及する。
• 能動態が使える箇所で受動態を使う。
• 平易な言葉で表現できるのに、長い単語、外国語の表現、専門用語を使う。