スタイルガイド

Istioドキュメントに受け入れられるすべてのコンテンツは、明確で理解しやすいものでなければなりません。その判断基準として、Googleデベロッパー スタイルガイドのハイライトと基本原則で定義されたものを採用しています。コンテンツの投稿がどのようにレビューされ、受け入れられるかについては、レビューページをご覧ください。

ここでは、Istioプロジェクトが異なる慣例に従うことや、Istio固有の例を用いた基本的なスタイルガイドを適用することを決定したすべてのシナリオを確認できます。

見出しには文の先頭を大文字にする（sentence case）

ドキュメントの見出しには、センテンスケースを使用してください。固有名詞や頭字語を除き、見出しの最初の単語のみを大文字にします。

フロントマターのtitle:フィールドの値にはタイトルケースを使用する

フロントマターのtitle:フィールドのテキストには、タイトルケースを使用する必要があります。接続詞と前置詞を除くすべての単語の最初の文字を大文字にします。

現在形を使用する

例外：正しい意味を伝えるために必要な場合は、未来形または過去形を使用してください。この例外は非常にまれであり、避けるべきです。

能動態を使用する

シンプルで直接的な言葉を使用する

シンプルで直接的な言葉を使用してください。「お願いします」などの不要なフレーズの使用は避けてください。

読者に「あなた」と語りかける

役立つリンクを作成する

良いハイパーリンクと悪いハイパーリンクがあります。リンクをここやここをクリックと呼ぶ一般的な慣習は、悪いハイパーリンクの例です。良いハイパーリンクとは何かを説明したこの記事を参照し、サイトコンテンツを作成またはレビューする際は、これらのガイドラインを念頭に置いてください。

「私たち」の使用を避ける

文中で「私たち」を使用すると、読者が自分が記述されている「私たち」の一部であるかどうか分からなくなる可能性があるため、混乱を招く可能性があります。

専門用語やイディオムを避ける

英語を第二言語として話す読者もいます。理解を容易にするために、専門用語やイディオムは避けてください。

未来についての記述を避ける

将来に関する約束やヒントを与えることは避けてください。開発中の機能について説明する必要がある場合は、フロントマターの下に情報を適切に識別する定型文を追加してください。

すぐに古くなる記述を避ける

「現在」や「新しい」など、すぐに古くなるような表現は避けてください。今日新しい機能は、長く新しいままではありません。