ドキュメントスタイルガイド

公式のスタイルガイドはまだありませんが、現在の OpenTelemetry ドキュメントのスタイルは以下のスタイルガイドに触発されています。

• Google Developer Documentation Style Guide
• Kubernetes Style Guide

後述するセクションは、OpenTelemetry プロジェクト特有のガイドを含んでいます。

OpenTelemetry.io ワードリスト

OpenTelemetry 特有の用語や単語の一覧であり、サイト全体で一貫して利用されるべきもの。

• OpenTelemetry と OTel
• コレクター
• OTEP
• OpAMP

OpenTelemetry の用語と定義の完璧なリストには、用語集 を参照してください。

ほかの CNCF プロジェクトやサードパーティツールなどの固有名詞は、適切に表記し、元の大文字・小文字の区別を正しく維持してください。 たとえば、“postgre” のかわりに “PostgreSQL” と表記してください。 すべてのリストは、.textlintrc.yml を確認してください。

Markdown

サイトページは、Goldmark Markdown レンダラーがサポートする Markdown 構文で書かれています。 サポートされている Markdown 拡張の完全な一覧は、Goldmark を参照してください。

次の Markdown 拡張も使用できます。

• アラート
• 絵文字: 利用可能な絵文字の完全な一覧は、Hugo ドキュメントの Emojis を参照してください。

アラート

次の拡張構文を使用してアラートを書けます。

• GitHub-flavored Markdown（GFM）の alerts
• カスタムアラートタイトル用の Obsidian callout 構文

それぞれの例を以下に示します。

> [!TIP]
>
> 新しいコンテンツを書く場合は、通常、Docsy の
> [alert ショートコード](https://www.docsy.dev/docs/content/shortcodes/#alert) ではなく、
> この blockquote alert 構文を使うことを推奨します。

> [!WARNING] :warning: 空行が必要です！
>
> このサイトでは [Prettier] フォーマッターを使用しており、alert タグ/タイトルと
> alert 本文の間に空行が必要です。

これは次のようにレンダリングされます。

blockquote alert 構文の詳細は、Docsy ドキュメントの Alerts を参照してください。

リンク参照

Markdown の reference links を使用する場合は、shortcut 形式の [text] よりも、collapsed 形式の [text][] を推奨します。 どちらも有効な CommonMark ですが、shortcut 形式はすべての Markdown ツールで一貫して認識されるわけではありません。 特に、[example] と書いて定義を書き忘れた場合、markdownlint linter は警告しません¹。 そのテキストはリンクではなく、リテラルの [example] として静かにレンダリングされます。 collapsed 形式の [example][] であれば、linter が定義の欠落を即座に検出します。

これは no-shortcut-ref-link カスタムルールによって強制されています。 shortcut reference を自動的に変換するには、npm run fix:markdown を実行してください。

Markdown チェック

Markdown ファイルの標準と一貫性を強制するため、すべてのファイルは markdownlint によって強制される特定のルールに従う必要があります。 すべてのルールの一覧は、.markdownlint.yaml と .markdownlint-cli2.yaml ファイルを確認してください。

ルールに対する正当な例外がある場合は、markdownlint-disable ディレクティブを使用してルールの警告を抑制してください。 詳細は markdownlint documentation を参照してください。

同様に、Markdown file format を適用し、ファイルの末尾スペースを削除します。 これは 2 つ以上のスペースを使用する line break syntax を排除します。 かわりに <br> を使うか、再フォーマットしてください。

スペルチェック

すべてのテキストが正しく表記されているか確認するために、CSpell を使用します。

cspell が「Unknown word」を報告した場合は、単語を正しく記述したか確認してください。 正しい場合は、次のいずれかの場所に単語を追加します。

• ページのフロントマターにある、ページローカルの cSpell:ignore リスト。 詳細は以下を参照してください。
• ロケール固有の単語リストファイル
• 汎用の all-words.txt 単語リスト

ページローカルの cSpell:ignore リスト

未知の単語が 1 つまたは少数のページにだけ現れる場合は、ページのフロントマターにあるページローカルの cSpell:ignore リストに追加します。

---
title: PageTitle
cSpell:ignore: <word>
---

ほかのファイルの場合は、そのファイルの状況に適したコメント行に cSpell:ignore <word> を追加してください。 たとえば、レジストリ エントリー YAML ファイルでは、次のように記述します。

# cSpell:ignore <word>
title: registryEntryTitle

単語リストファイル

未知の単語が複数のページに現れる場合や技術用語である場合は、ロケール固有の単語リストファイルに追加します。 単語リストファイルは .cspell/ ディレクトリにあります。

opamp のように、すべてのロケールで正しいスペルの単語であれば、all-words.txt ファイルに追加します。

ファイルのフォーマット

Prettier を利用することでファイルフォーマットを強制します。 次を使用して実行します。

• npm run fix:format: すべてのファイルをフォーマットします
• npm run fix:format:diff: 直近のコミットから変更されたファイルだけをフォーマットします
• npm run fix:format:staged: 次のコミット用にステージされたファイルだけをフォーマットします

ファイル名

すべてのファイル名は、kebab case である必要があります。

検証問題の修正

検証問題の修正方法については、プルリクエストのチェック を参照してください。