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

公式のスタイルガイドはまだありませんが、現在の 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 ファイルを確認してください。

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

スペルチェック

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

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

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

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

# cSpell:ignore <word>
title: registryEntryTitle

ファイルのフォーマット

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

ファイル名

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

検証問題の修正

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