adev-writing-guide

Angular ドキュメント（adev）執筆ガイド

このスキルでは、adev/src/content のコンテンツを執筆するための包括的なガイドラインを紹介します。Google のテクニカルライティング基準に、Angular 固有の Markdown の規約、コンポーネント、ベストプラクティスを組み合わせています。

I. Google テクニカルライティングガイドライン

トーンと内容

• 親しみやすく、会話的に書く： 役立つプロフェッショナルなトーンを保ちます。くだけすぎないようにします。
• わかりやすく書く： 英語を母語としない人を含む、世界中の多様な読者が理解できるドキュメントにします。
• 読者を第一に考える： システムの動作だけでなく、ユーザーが何をする必要があるかに焦点を当てます。
• 事前告知を避ける： 未リリースの機能に言及したり、根拠のない主張をしたりしないでください。
• 説明的なリンクテキストを使う： リンクテキストからリンク先が明確にわかるようにします（「ここをクリック」は避けます）。

言葉遣いと文法

• 二人称（「あなた」）を使う： 読者に直接呼びかけます。
• 能動態を優先する： 誰が、または何が動作を行うのかを明確に示します（例：「システムがトークンを生成します」。「トークンが生成されます」ではありません）。
• 標準的なアメリカ英語を使う： 標準的なアメリカ英語の綴りと句読点を使います。
• 条件節を先に置く： 指示の前に「if」または「when」の節を置きます（例：「エラーが発生した場合は、ログを確認してください」）。
• 用語を定義する： 新しい用語やなじみのない用語、略語は、初出時に説明します。
• 用語を統一する： 同じ概念には、ドキュメント全体で同じ用語を使います。
• 簡潔にする： 1つの文につき1つの考えを伝えるようにします。文は短くします。

書式と構成

• 見出しはセンテンスケースにする： タイトルと見出しでは、最初の単語と固有名詞のみを大文字にします。
• リスト：
  • 番号付きリスト： 順序のある手順や優先順位付きの項目に使います。
  • 箇条書きリスト： 順序のない項目の列挙に使います。
  • 定義リスト： 用語と定義の組み合わせに使います。
• シリアルカンマ： 3つ以上の項目を列挙する場合、最後の項目の前に Oxford comma を使います。
• コードの書式： ファイル名、変数、コマンドなど、コードに関連するテキストにはコードフォントを使います。
• UI 要素： ユーザーインターフェースの要素は太字で書式設定します。
• 日付の書式： 曖昧さのない形式を使います（例：「9/4/2024」ではなく「September 4, 2024」）。
• 構成： 明確な導入とナビゲーションを備えた論理的な階層にします。可能な限り、見出しはタスクベースにします。

画像とコードサンプル

• 画像： 理解を深めるために、シンプルで明確な図を使います。
• キャプション： 画像を補足するキャプションを書きます。
• コードサンプル：
  • コードが正しく、エラーなくビルドできることを確認します。
  • 各言語固有の規約に従います。
  • コメント： _何をするか_ではなく、_なぜそうするか_に焦点を当てます。自明なコードへのコメントは避けます。

参照資料の優先順位

1. プロジェクト固有のスタイルガイドライン（CONTRIBUTING.md などにある場合）。
2. Google Developer Documentation Style Guide。
3. Merriam-Webster（綴り）。
4. Chicago Manual of Style（非技術文書）。
5. Microsoft Writing Style Guide（技術文書）。

---

II. Angular ドキュメント固有のガイドライン

コードブロック

シンタックスハイライトには、適切な言語識別子を使います。

• TypeScript（Angular）： TypeScript のコード例にインラインテンプレートが含まれる場合は、angular-ts を使います。
• HTML（Angular）： Angular テンプレートには angular-html を使います。
• TypeScript（汎用）： 通常の TypeScript には ts を使います。
• HTML（汎用）： 通常の HTML には html を使います。
• シェル／ターミナル： shell または bash を使います。
• Mermaid 図： mermaid のフェンス付きコードブロックを使います。<docs-code language="mermaid"> はサポートされておらず、ビルドが失敗します。

属性

言語識別子の後に波かっこ {} で属性を指定すると、コードブロックを拡張できます。header と highlight はコロンの後に値を指定します。それ以外は値を持たないフラグです。flag: true のように記述すると Invalid code block metadata でビルドに失敗します。また、認識されないキーを指定した場合も同様です。

• header: "Title"：コードブロックにタイトルを追加します。
• linenums：行番号を有効にします。
• highlight: [2]：特定の行をハイライトします。昇順の2つの数字を含む配列は範囲として扱われるため、[12, 19] は12行目から19行目をハイライトします。数字が1つの場合、または3つ以上の場合は、個別の行番号のリストとして扱われます。2種類を組み合わせるには、1段階ネストします。例：[[3,7], 9]
• hideCopy：コピー ボタンを非表示にします。
• hideDollar：シェルの例で $ プロンプトを非表示にします。
• prefer：コードを推奨例として示します（緑色の枠線とチェックマーク）。
• avoid：コードを避けるべき例として示します（赤色の枠線とバツ印）。

例：

```angular-ts {header: "My Component", linenums, highlight: [2]}
@Component({
  selector: 'my-app',
  template: '<h1>Hello</h1>',
})
export class App {}
```

<docs-code> コンポーネント

より高度なコードブロック機能を使うには、<docs-code> コンポーネントを使用します。属性には HTML 構文を使用し、attr="value" のように二重引用符で値を指定します。ブール属性は名前だけを記述します。検証は行われないため、認識されない属性も、値を一重引用符で囲んだ場合も、エラーにならず無視されます。

• path：ソースファイルへのパス（例：adev/src/content/examples/...）。
• header：カスタムヘッダーテキスト。
• language：言語識別子（例：angular-ts）。省略した場合はファイル拡張子から推定されます。認識されない拡張子は angular-ts として扱われるため、シェル、マークダウン、scss ファイルでは指定してください。
• linenums：ブール属性。
• highlight：行番号または行範囲の配列。フェンス付きコードブロックと同じ仕様です（例：[[3,7], 9]）。
• visibleLines：最初に表示する行の範囲（折りたたみ可能）。
• region：ソースファイルから抽出する領域。
• preview：ブール値。コードの下に、例を実行中のコンポーネントとして表示します。スタンドアロンの例でのみ動作します。
• hideCode：ブール値。コードをデフォルトで折りたたみます。
• hideDollar：シェルの例で $ プロンプトを非表示にします。
• prefer / avoid：例を推奨例、または避けるべき例として示します。

複数ファイルの例：

<docs-code-multifile path="..." preview>
  <docs-code path="..." />
  <docs-code path="..." />
</docs-code-multifile>

アラート／注釈

アラートを表示するには、特定のキーワードの後にコロンを付けて使用します。これらはスタイル付きブロックとして表示されます。

• NOTE: 補足情報に使用します。
• TIP: 役立つヒントやショートカットに使用します。
• IMPORTANT: 重要な情報に使用します。
• CRITICAL: データ損失の可能性や重大な問題に関する警告に使用します。
• TODO: 未完成のドキュメントに使用します。
• QUESTION: 読者に質問する場合に使用します。
• SUMMARY: セクションの要約に使用します。
• TLDR: 簡潔な要約に使用します。
• HELPFUL: ベストプラクティスに使用します。

例：

TIP: Use `ng serve` to run your application locally.

カスタムコンポーネント

• カード（<docs-card>）：
  • 通常は <docs-card-container> 内に配置します。カードが1つだけの場合は、単独でも表示されます。
  • 属性：title、href、link、imgSrc、iconImgSrc、titleInline。
  • href はリンク先を指定します。link はデフォルトの「Learn more」ラベルのみを置き換えるため、link に URL を指定するとテキストとして表示されます。また、href のないカードはクリックできません。
• コールアウト（<docs-callout>）：
  • 属性：title、important、critical。
• ピル（<docs-pill>）：
  • <docs-pill-row> 内に配置する必要があります。
  • 属性：title、href。
• ステップ／ワークフロー（<docs-step>）：
  • <docs-workflow> 内に配置する必要があります。
  • 属性：title。
• タブ（<docs-tab>）：
  • <docs-tab-group> 内に配置する必要があります。
  • 属性：label。
• 動画（<docs-video>）：
  • 属性：src（YouTube 埋め込み URL）、title（再生リンクのラベルに表示する動画名）。

画像

サイズや読み込み動作の属性を任意で指定して、標準的なマークダウン構文を使用します。

• #small、#medium：サイズ指定のため、画像 URL の末尾に追加します。
• {loading: 'lazy'}：遅延読み込みの属性を追加します。

例：

![Alt Text](path/to/image.png#medium {loading: 'lazy'})

見出し

• マークダウンの見出し（#、##、###）を使用します。
• 論理的な階層を保ちます（レベルを飛ばさないでください）。
• コンテンツ構成には、h2 と h3 を使用することが最も一般的です。