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

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

• Google Developer Documentation Style Guide
• Kubernetes Style Guide

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

OpenTelemetry.io ワードリスト

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

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

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

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

マークダウン規約

マークダウンファイルに規約と一貫性を確保するために、markdownlint によって定められたルールに従う必要があります。 すべてのルールの一覧は、.markdownlint.json ファイルを確認してください。

以下を実行してください。

• npm run check:markdown はすべてのファイルが規約に従っていることを保証します。
• npm run fix:markdown はマークダウンに関連するフォーマットの問題を修正します。

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

スペルチェック

すべてのテキストが適切に表記されているあ確認するために、CSpell を使用します。 OpenTelemetry ウェブサイト固有の単語一覧は、.cspell.yml ファイルを確認してください。

すべての単語が正しいことを確認するために、npm run check:spelling を実行してください。 cspell が Unknown word エラーを示した場合、単語を正しく記述したか確認してください。 正しく場合、ファイルの先頭にある cSpell:ignore セクションに単語を追加してください。 そのようなセクションがない場合は、Markdown ファイルの Front Matter に追加できます。

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

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

# cSpell:ignore <word>
title: registryEntryTitle

ウェブサイトのツールは、重複した単語の排除、グローバル単語リストにある単語を削除、単語をソートすることで、ページ固有の辞書（つまり、cSpell:ignore 単語リスト）を標準化します。 ページ固有の辞書を標準化するには、npm run fix:dict を実行してください。

ファイルのフォーマット

Prettier を利用することでファイルフォーマットを強制します。 npm run fix:format を実行して、フォーマットを適用してください。

ファイル名

すべてのファイル名は、kebab case である必要があります。 npm run fix:filenames を実行して、ファイルを自動的にリネームしてください。