スタイルガイド

このスタイルガイドは、用語集の読者、定義の構造、必要な詳細度、一貫したスタイルを維持する方法について理解するのに役立ちます。

クラウドネイティブ用語集は、CNCFリポジトリのデフォルトスタイルガイドに従っています。 さらに、以下のルールにも従っています：

  1. 専門用語や流行語は避け、シンプルでわかりやすい言葉を使う。
  2. 口語を避ける
  3. 書き言葉や具体的な言葉を使う
  4. 前置詞と冠詞の縮約を含めない
  5. 受動態は慎重に使う
  6. 肯定形でのフレーズを目指す
  7. 引用符以外の感嘆符を使用しない
  8. 誇張しないこと
  9. 繰り返しを避ける
  10. 簡潔であること

読者

用語集は、技術者および技術者以外の読者を対象として書かれています。 技術的な知識を前提とせず、定義が簡単な言葉で説明されていることを確認してください。詳しくは、以下の定義をご覧ください。

最小限の定義

私たちの目標は、クラウドネイティブの用語を誰でも本当に簡単に理解できるようにすることです。 そのため、シンプルであることに重点を置いています。 つまり、テクノロジーを使っている人なら誰でも共感できるような例を用いて、明確でシンプルな言葉を使うということです（詳しくは後述します）。また、少なくとも技術的な観点からは、最小限の定義を提供します。 文脈や例を節約するつもりはありません。結局のところ、それらは読者がコンセプトを理解するのに役立ちますが、技術的な詳細が理解に必要でない場合は、それを省略します。 目標は、物事を複雑にし過ぎないことです。読者が基本的なコンセプトを理解したら、他のリソースでより深く掘り下げることができるようにします。その部分はこの用語集の範囲外です。

定義のテンプレート

各用語はマークダウンファイルに格納され、このテンプレートに従います：

---
title: 
status: 
category: 
---

技術やコンセプトの簡単な要約。

## 解決すべき問題はなんですか

取り組んでいる問題について数行。

## どのように役に立つのでしょうか

それがどのように問題を解決するのか数行。

タイトル

タイトル ラベルは、常に定義レイアウトの先頭に位置し、その値はタイトルケースであるべきです。

---
title: Definition Template

状態

状態 ラベルは、タイトルラベルの後に表示されます。状態ラベルは、定義が十分に吟味されているか、より多くの努力を必要とするかを示します。

有効な値は以下の通りです：

  • Completed（完了）
  • Feedback Appreciated（フィードバックが必要です）
  • Not Started（未着手）

完了した定義に対して、いつでもissueを開くことができます。定義が流動的な場合、そのステータスはFeedback Appreciatedに変更されます。

---
title: Definition Template
status: Feedback Appreciated

タグ

ステータスラベルの後に、タグ ラベルが続きます。 タグが意味を持ち、結果としてユーザーの役に立つためには、タグを厳密な意味で使うことになります。 多くのタグを付けると、その意味が薄れるだけです。 他のクラウドネイティブの概念を理解するために必要な用語であることを示すfundamental（基礎）を除き、ほとんどの用語のタグは1つだけとなる可能性があります。

注意： 管理者の承認がない限り、新しいタグを導入しないでください。エントリにタグを追加する場合は、以下のリストにあるように正確に綴るようにしてください（単数形、タイプミスなし）。

現在のタグは以下の通りです：

  • application（アプリケーション）
  • architecture（アーキテクチャ）
  • fundamental（基礎）
  • infrastructure（インフラストラクチャー）
  • methodology（方法論）
  • networking（ネットワーキング）
  • property（プロパティ）
  • security（セキュリティ）
---
title: Definition Template
status: Feedback Appreciated
tags: ["tag 1"], ["tag 2"]
---

定義

2つの副題

テクノロジー と コンセプト のカテゴリの定義には、簡単な概要と2つの副題があります：

  • (簡単な概要) : 私たちが話していることについて、短く明確な概要を提供します。
  • 解決すべき問題はなんですか : 問題に焦点を当て、解決策（それは次のセクションで出てきます）には触れないようにします。 実際、定義されている用語に言及するのは避けましょう。問題は、私たちがそのモノを必要とするようになった きっかけ に焦点を当てます。
  • どのように役に立つのでしょうか : さて、その用語に戻りましょう。その用語は、上記の問題にどのように対処するのでしょうか？

なお、プロパティは別項目を必要としません。定義で十分です。

レビューを容易にするために、セマンティック改行（1行に1文）を使ってください。

品質を最優先する

マージされると、あなたの投稿がその用語の公式なCNCF定義となります（他の誰かが改良するまで）。 CNCFの高い基準を満たす用語の作成は、急ぐことはできません - 品質には時間と努力が必要です。

よく調べてください：その用語を知っていると自信があっても、正しく理解できているかどうか確認してください。 私たちはしばしば、組織の中で用語を特定の方法で使用しますが、それは全体像を反映していないかもしれません。 特に、その用語に100％精通しているわけではない場合、複数のリソースを使用して調査してください。 特にベンダーが提供する場合、多くの定義が一方的なものである。 用語集には、ベンダーニュートラルで、世界的に認められた定義が含まれていなければなりません。

盗作はしないこと：用語集には、他の真面目な出版物と同じルールが適用されます。 引用して寄稿している場合を除き、他人の著作物をコピー＆ペーストしてはいけません。 定義の特定の部分が気に入った場合は、自分の言葉で言い換えてください。

権威あるリソースを参照する：可能であれば、プロジェクトのドキュメントなどの権威あるリソースにリンクしてください。 ベンダーが開発したコンテンツへのリンクはできませんのでご注意ください。

シンプルであること

用語集は、複雑な概念を簡単な言葉で説明することを目的としていますが、これは意外と難しい作業で、何度も改訂が必要になります。 定義を作成する際には、常に読者を念頭に置いてください。 業界用語や流行語の使用は避けてください。きっと、つい見返してしまい、自動修正が必要になるかもしれません。

適切な場合は、読者（特に非技術者）が、説明しているコンセプトが いつ、なぜ 関連しているのかをより理解しやすくするために、実例 を使用します。

定義で使用する場合は、必ず 既存の用語集にリンクしてください （最初の言及のみハイパーリンクする必要があります）。

例：サービスメッシュの定義の概要セクションを見てみましょう。 マイクロサービス、サービス、信頼性、観測可能性の定義とリンクしています。 さらに、マイクロサービス環境におけるネットワークの課題（非技術者が共感できないもの）と無線LANの問題（ノートパソコンを使っている人なら理解できるもの）を比較した実例を用いています。可能な限り、そのつながりを作るようにしてください。

Google や Word のドキュメントから始める

GoogleやWordのドキュメントから始めて、数日置いてから、もう一度見直してみることをお勧めします。 そうすることで、よりシンプルでわかりやすい表現ができるフレーズや表現をキャッチすることができます。 また、PRを提出する前に、必ずスペルチェックを行いましょう。

ある用語に取り組んでいるときに、他の人がPRを提出しないようにするには、issueを要求し（または作成し）、そのissueが自分に割り当てられるようにする必要があります。 詳しくは、貢献の仕方 ドキュメントをご覧ください。

始める前に、詳細や難易度、例文が適切に感じるか公開されている用語集をいくつか読んでください。

レビュープロセス：期待されること

現在、私たちは3人のメンテナンス担当者だけが、余暇を利用してこの作業を行っていることにご注意ください。 時には、すぐに用語の見直しができることもありますが、時間がかかることもあります。 ご不明な点がございましたら、Slackの#glossaryチャンネルでお問い合わせください。 (チャンネルがある場所と方法については、貢献の仕方 ドキュメントを参照してください)。

私たちの目標は、用語集が可能な限り最高のリソースとなるようにすることです。 あなたがPRを提出すると、私たちは1つまたは複数の修正をお願いすることがあります。 挫折しないでください、多くのPRでそうなっています。 このようなやり取りと私たちの協力によって、あなたの投稿が、世界中の読者に読まれ、参照される、本当に役立つ定義になることを保証します。

最終更新日 December 2, 2023: Update service mesh link (3cb892c)