K8sのドキュメントに貢献する

• 1: コンテンツの改善を提案する
• 2: 新しいコンテンツの貢献
• 3: 変更のレビュー
• 3.1: プルリクエストのレビュー
• 3.2: approverとreviewer向けのレビュー
• 4: Kubernetesのドキュメントを翻訳する
• 5: SIG Docsへの参加
• 6: ドキュメントスタイルの概要
• 6.1: ドキュメントコンテンツガイド
• 6.2: コンテンツの構造化
• 6.3: カスタムHugoショートコード

1 - コンテンツの改善を提案する

Kubernetesのドキュメントに何か問題を見つけたり、新しいコンテンツに関してアイデアを思い付いたときは、issueを作ってください。必要なものは、GitHubアカウントとウェブブラウザーだけです。

Kubernetesのドキュメント上の新しい作業は、ほとんどの場合、GitHubのissueから始まります。Kubernetesのコントリビューターは、必要に応じてレビュー、分類、タグ付けを行います。次に、あなたやKubernetesコミュニティの他のメンバーが、そのissueを解決するための変更を加えるpull requestを開きます。

issueを作る

既存のコンテンツに対して改善を提案したい場合や、間違いを発見した場合は、issueを作ってください。

1. ページの右側のサイドバーにあるドキュメントのissueを作成ボタンをクリックします。GitHubのissueページにリダイレクトし、一部のヘッダーが自動的に挿入されます。
2. 問題や改善の提案について書きます。できる限り多くの詳細情報を提供するようにしてください。
3. Submit new issueボタンをクリックします。

送信後、定期的にissueを確認するか、GitHubの通知を設定してください。レビュアや他のコミュニティメンバーが、issueに対して作業を行うために、あなたに何か質問をするかもしれません。

新しいコンテンツの提案

新しいコンテンツに関するアイデアがあるものの、どの場所に追加すればわからないときでも、issueを作ることができます。次のいずれかを選択して行ってください。

• コンテンツが追加されるべきだと思う既存のページを選択し、ドキュメントのissueを作成ボタンをクリックする。
• GitHubに移動し、直接issueを作る。

よいissueを作るには

issueを作るときは、以下のことを心に留めてください。

• 明確なissueの説明を書く。不足している点、古くなっている点、誤っている点、改善が必要な点など、どの点がそうであるか明確に書く。
• issueがユーザーに与える具体的な影響を説明する。
• 合理的な作業単位になるように、特定のissueのスコープを制限する。スコープの大きな問題については、小さな複数のissueに分割する。たとえば、"Fix the security docs"(セキュリティのドキュメントを修正する)というのはスコープが大きすぎますが、"Add details to the 'Restricting network access' topic"(トピック「ネットワークアクセスの制限」に詳細情報を追加する)であれば十分に作業可能な大きさです。
• すでにあるissueを検索し、関連または同様のissueがないかどうか確認する。
• 新しいissueがほかのissueやpull requestと関係する場合は、完全なURLを参照するか、issueやpull requestの数字の前に#の文字を付けて参照する。例えば、Introduced by #987654のように書きます。
• 行動規範に従って、仲間のコントリビューターに敬意を払いましょう。たとえば、"The docs are terrible"(このドキュメントは最悪だ)のようなコメントは、役に立つ敬意のあるフィードバックではありません。

2 - 新しいコンテンツの貢献

このセクションでは、新しいコンテンツの貢献を行う前に知っておくべき情報を説明します。

図 - 新しいコンテンツ提供の貢献方法

上記の図は新しいコンテンツを申請する前に知っておくべき情報を示しています。 詳細については以下で説明します。

貢献の基本

• KubernetesのドキュメントはMarkdownで書き、KubernetesのウェブサイトはHugoを使ってビルドします。
• Kubernetesのドキュメントは、MarkdownのスタイルとしてCommonMarkを使用しています。
• ソースはGitHubにあります。Kubernetesのドキュメントは/content/en/docs/にあります。リファレンスドキュメントの一部は、update-imported-docs/ディレクトリ内のスクリプトから自動的に生成されます。
• Page content typesにHugoによるドキュメントのコンテンツの見え方を記述しています。
• Kubernetesのドキュメントに貢献するのにDocsy shortcodeやカスタムのHugo shortcodeが使えます。
• 標準のHugoのshortcodeに加えて、多数のカスタムのHugo shortcodeを使用してコンテンツの見え方をコントロールしています。
• ドキュメントのソースは/content/内にある複数の言語で利用できます。各言語はそれぞれISO 639-1標準で定義された2文字のコードの名前のフォルダを持ちます。たとえば、英語のドキュメントのソースは/content/en/docs/内に置かれています。
• 複数言語でのドキュメントへの貢献や新しい翻訳の開始に関する情報については、Kubernetesのドキュメントを翻訳するを参照してください。

始める前に

CNCF CLAに署名する

すべてのKubernetesのコントリビューターは、コントリビューターガイドを読み、Contributor License Agreement(コントリビューターライセンス契約、CLA)への署名を必ず行わなければなりません。

CLAへの署名が完了していないコントリビューターからのpull requestは、自動化されたテストで失敗します。名前とメールアドレスはgit configコマンドで表示されるものに一致し、gitの名前とメールアドレスはCNCF CLAで使われたものに一致しなければなりません。

どのGitブランチを使用するかを選ぶ

pull requestをオープンするときは、どのブランチをベースにして作業するかをあらかじめ知っておく必要があります。

それでも選ぶべきブランチがわからないときは、Slack上の#sig-docsチャンネルで質問してください。

言語ごとのPR

pull requestはPRごとに1つの言語に限定してください。複数の言語に同一の変更を行う必要がある場合は、言語ごとに別々のPRを作成してください。

コントリビューターのためのツール

kubernetes/websiteリポジトリ内のdoc contributors toolsディレクトリには、コントリビューターとしての旅を楽にしてくれるツールがあります。

3 - 変更のレビュー

このセクションでは、コンテンツのレビュー方法について説明します。

3.1 - プルリクエストのレビュー

ドキュメントのプルリクエストは誰でもレビューすることができます。Kubernetesのwebsiteリポジトリでpull requestsのセクションに移動し、open状態のプルリクエストを確認してください。

ドキュメントのプルリクエストのレビューは、Kubernetesコミュニティに自分を知ってもらうためのよい方法の1つです。コードベースについて学んだり、他のコントリビューターとの信頼関係を築く助けともなるはずです。

レビューを行う前には、以下のことを理解しておくとよいでしょう。

• コンテンツガイドとスタイルガイドを読んで、有益なコメントを残せるようにする。
• Kubernetesのドキュメントコミュニティにおける役割と責任の違いを理解する。

はじめる前に

レビューを始める前に、以下のことを心に留めてください。

• CNCFの行動規範を読み、いかなる時にも行動規範にしたがって行動するようにする。
• 礼儀正しく、思いやりを持ち、助け合う気持ちを持つ。
• 変更点だけでなく、PRのポジティブな側面についてもコメントする。
• 相手の気持ちに共感して、自分のレビューが相手にどのように受け取られるのかをよく意識する。
• 相手の善意を前提として、疑問点を明確にする質問をする。
• 経験を積んだコントリビューターの場合、コンテンツに大幅な変更が必要な作業を行う新規のコントリビューターとペアを組んで取り組むことを考える。

レビューのプロセス

一般に、コンテンツや文体に対するプルリクエストは、英語でレビューを行います。図1は、レビュープロセスについて手順の概要を示しています。 各ステップの詳細は次のとおりです。

(訳注:SIG Docs jaでは、日本語でも対応しています。日本語の翻訳に対するレビューは、日本語でも構いません。ただし、プルリクエストの作成者や他のコントリビューターが必ずしも日本語を理解できるとは限りませんので、注意して発言してください。)

図1. レビュープロセスの手順

1. https://github.com/kubernetes/website/pullsに移動します。Kubernetesのウェブサイトとドキュメントに対するopen状態のプルリクエスト一覧が表示されます。

2. open状態のPRに、以下に示すラベルを1つ以上使って絞り込みます。

   • cncf-cla: yes (推奨): CLAにサインしていないコントリビューターが提出したPRはマージできません。詳しい情報は、CLAの署名を読んでください。
   • language/en (推奨): 英語のPRだけに絞り込みます。
   • size/<size>: 特定の大きさのPRだけに絞り込みます。レビューを始めたばかりの人は、小さなPRから始めてください。

   さらに、PRがwork in progressとしてマークされていないことも確認してください。work in progressラベルの付いたPRは、まだレビューの準備ができていない状態です。

3. レビューするPRを選んだら、以下のことを行い、変更点について理解します。

   • PRの説明を読み、行われた変更について理解し、関連するissueがあればそれも読みます。
   • 他のレビュアのコメントがあれば読みます。
   • Files changedタブをクリックし、変更されたファイルと行を確認します。
   • Conversationタブの下にあるPRのbuild checkセクションまでスクロールし、Netlifyのプレビュービルドで変更点をプレビューします。これはスクリーンショットです(これは、GitHubのデスクトップサイトを見せています。タブレットやスマートフォンデバイスでレビューしている場合は、GitHubウェブのUIは少し異なります):

     

     プレビューを開くには、チェックリストのdeploy/netlify行のDetailsリンクをクリックします。

4. Files changedタブに移動してレビューを始めます。

   1. コメントしたい場合は行の横の+マークをクリックします。

   2. その行に関するコメントを書き、Add single comment(1つのコメントだけを残したい場合)またはStart a review(複数のコメントを行いたい場合)のいずれかをクリックします。

   3. コメントをすべて書いたら、ページ上部のReview changesをクリックします。ここでは、レビューの要約を追加できます(コントリビューターにポジティブなコメントも書きましょう！)。常に「Comment」を使用してください。

      • レビューの終了時、「Request changes」ボタンをクリックしないでください。さらに変更される前にマージされるのをブロックしたい場合、「/hold」コメントを残すことができます。Holdを設定する理由を説明し、必要に応じて、自分や他のレビューアがHoldを解除できる条件を指定してください。
      • レビューの終了時、「Approve」ボタンをクリックしないでください。大抵の場合、「/approve」コメントを残すことが推奨されます。

レビューのチェックリスト

レビューするときは、最初に以下の点を確認してみてください。

言語と文法

• 言語や文法に明らかな間違いはないですか？ もっとよい言い方はないですか？
  • 作成者が変更している箇所の用語や文法に注目してください。作成者がページ全体の変更を目的として明確にしていない限り、そのページのすべての問題を修正する義務はありません。
  • 既存のページを変更するPRである場合、変更されている箇所に注目してレビューしてください。その変更されたコンテンツは、技術的および編集の正確性についてレビューしてください。PRの作成者が対処しようとしている内容と直接関係のない間違いを見つけた場合、それは別のIssueとして扱うべきです(既存のIssueが無いことを確認してください)。
  • コンテンツを移動するPull Requestに注意してください。作成者がページの名前を変更したり、2つのページを結合したりする場合、通常、私たち(Kubernetes SIG Docs)は、その移動されたコンテンツ内で見つけられるすべての文法やスペルの間違いを修正することを作成者に要求することを避けています。
• もっと簡単な単語に置き換えられる複雑な単語や古い単語はありませんか？
• 使われている単語や専門用語や言い回しで差別的ではない別の言葉に置き換えられるものはありませんか？
• 言葉選びや大文字の使い方はstyle guideに従っていますか？
• もっと短くしたり単純な文に書き換えられる長い文はありませんか？
• 箇条書きやテーブルでもっとわかりやすく表現できる長いパラグラフはありませんか？

コンテンツ

• 同様のコンテンツがKubernetesのサイト上のどこかに存在しませんか？
• コンテンツが外部サイト、特定のベンダー、オープンソースではないドキュメントなどに過剰にリンクを張っていませんか？

ウェブサイト

• PRはページ名、slug/alias、アンカーリンクの変更や削除をしていますか？ その場合、このPRの変更の結果、リンク切れは発生しませんか？ ページ名を変更してslugはそのままにするなど、他の選択肢はありませんか？
• PRは新しいページを作成するものですか？ その場合、次の点に注意してください。
  • ページは正しいpage content typeと関係するHugoのshortcodeを使用していますか？
  • セクションの横のナビゲーションにページは正しく表示されますか(または表示されませんか)？
  • ページはDocs Homeに一覧されますか？
• Netlifyのプレビューで変更は確認できますか？ 特にリスト、コードブロック、テーブル、備考、画像などに注意してください。

その他

• 些細な編集に注意してください。些細な編集だと思われる変更を見つけた場合は、そのポリシーを指摘してください (それが本当に改善である場合は、変更を受け入れても問題ありません)。
• 空白の修正を行っている作成者には、PRの最初のコミットでそれを行い、その後に他の変更を加えるよう促してください。これにより、マージとレビューの両方が容易になります。特に、大量の空白文字の整理と共に1回のコミットで発生する些細な変更に注意してください(もしそれを見つけたら、作成者に修正を促してください)。

レビュアーが誤字や不適切な空白など、PRの本質でない小さな問題を発見した場合は、コメントの先頭にnit:を付けてください。これにより、作成者はこのフィードバックが重要でないことを知ることができます。

Pull Requestの承認を検討する際、残りのすべてのフィードバックがnitとしてマークされていれば、残っていたとしてもPRをマージできます。その場合、残っているnitに関するIssueをオープンすると役立つことがよくあります。その新しいIssueをGood First Issueとしてマークするための条件を満たすことができるかどうか検討してください。それができたら、これらは良い情報源になります。

3.2 - approverとreviewer向けのレビュー

SIG DocsのReviewer(レビュアー)とApprover(承認者)は、変更をレビューする時にいくつか追加の作業を行います。

毎週、docsのメンバーの特定のapproverのボランティアは、pull requestのトリアージとレビューを担当します。この担当者は、その週の「PR Wrangler(PRの世話人)」と呼ばれます。詳しい情報は、PR Wrangler schedulerを参照してください。PR Wranglerになるには、週次のSIG Docsミーティングに参加し、ボランティアをします。もしその週にスケジュールされていなくても、活発なレビューが行われていないpull request(PR)をレビューすることは問題ありません。

このローテーションに加えて、変更されたファイルのオーナーに基づいて、botがPRにreviewerとapproverを割り当てます。

PRをレビューする

KubernetesのドキュメントはKubernetesコードレビュープロセスに従います。

pull requestのレビューに書かれているすべてのことが適用されますが、ReviewerとApproverはそれに加えて次のことも行います。

• 必要に応じて、/assignProwコマンドを使用して、特定のreviewerにPRを割り当てる。これは、コードのコントリビューターからの技術的なレビューが必要な場合には特に重要です。

  備考: 技術的なレビューを行える人物を知るには、Markdownファイル上部にあるfront-matterのreviewersフィールドを確認してください。

• PRがコンテンツおよびスタイルのガイドに従っていることを確認してください。ガイドに従っていない場合は、ガイドの関連する部分にリンクを作者に示してください。

• PRの作者に変更を提案できるときは、GitHubのRequest Changes(変更をリクエスト)オプションを利用してください。

• 提案したことが反映されたら、/approveや/lgtmコマンドを使用して、GitHubのレビューステータスを変更してください。

他の作者のPRにコミットを追加する

PRにコメントを残すのは助けになりますが、まれに他の作者のPRに代わりにコミットを追加する必要がある場合があります。

あなたが明示的に作者から頼まれたり、長い間放置されたPRを蘇らせるような場合でない限り、他の作者のPRを「乗っ取る」ようなことはしないでください。短期的に見ればそのほうが短時間で終わるかもしれませんが、そのようなことをするとその人が貢献するチャンスを奪ってしまうことになります。

あなたが取る方法は、編集する必要のあるファイルがすでにPRのスコープに入っているか、あるいはPRがまだ触れていないファイルであるかによって変わります。

以下のいずれかが当てはまる場合、他の作者のPRにあなたがコミットを追加することはできません。

• PRの作者が自分のブランチを直接https://github.com/kubernetes/website/リポジトリにpushした場合。この場合、pushアクセス権限を持つreviewerしか他のユーザーのPRにコミットを追加することはできません。

  備考: 次回PRを作成するとき、自分のブランチを自分のforkに対してpushするように作者に促してください。

• PRの作者が明示的にapproverからの編集を禁止している場合。

レビュー向けのProwコマンド

Prowは、pull request(PR)に対してジョブを実行するKubernetesベースのCI/CDシステムです。Prowは、Kubernetes organization全体でchatbotスタイルのコマンドを利用してGitHub actionsを扱えるようにします。たとえば、ラベルの追加と削除、issueのclose、approverの割り当てなどが行なえます。Prowコマンドは、GitHubのコメントに/<command-name>という形式で入力します。

reviewerとapproverが最もよく使うprowコマンドには、以下のようなものがあります。

PRで利用できるすべてのコマンドを確認するには、Prowコマンドリファレンスを参照してください。

issueのトリアージとカテゴリー分類

一般に、SIG DocsはKubernetes issue triageのプロセスに従い、同じラベルを使用しています。

このGitHub issueのフィルターは、トリアージが必要な可能性があるissueを表示します。

issueをトリアージする

1. issueを検証する

• issueがドキュメントのウェブサイトに関係するものであることを確かめる。質問に答えたりリソースの場所を報告者に教えることですぐに閉じられるissueもあります。詳しくは、サポートリクエストまたはコードのバグレポートのセクションを読んでください。
• issueにメリットがあるかどうか評価する。
• issueに行動を取るのに十分な詳細情報がない場合や、テンプレートが十分埋められていない場合は、triage/needs-informationラベルを追加する。
• lifecycle/staleとtriage/needs-informationの両方のラベルがあるときは、issueをcloseする。

2. 優先度(priority)ラベルを追加する(issueトリアージガイドラインは、priorityラベルについて詳しく定義しています。)

あなたの裁量で、issueのオーナーシップを取り、issueに対するPRを提出してください(簡単なissueや、自分がすでに行った作業に関連するissueである場合は特に)。

issueのトリアージについて質問があるときは、Slackの#sig-docsかkubernetes-sig-docs mailing listで質問してください。

issueラベルの追加と削除

ラベルを追加するには、以下のいずれかの形式でコメントします。

• /<label-to-add>(たとえば、/good-first-issue)
• /<label-category> <label-to-add>(たとえば、/triage needs-informationや/language ja)

ラベルを削除するには、以下のいずれかの形式でコメントします。

• /remove-<label-to-remove>(たとえば、/remove-help)
• /remove-<label-category> <label-to-remove>(たとえば、/remove-triage needs-information)

いずれの場合でも、ラベルは既存のものでなければなりません。存在しないラベルを追加しようとした場合、コマンドは無視されます。

すべてのラベル一覧は、websiteリポジトリーのラベルセクションで確認できます。SIG Docsですべてのラベルが使われているわけではありません。

issueのライフサイクルに関するラベル

issueは一般にopen後に短期間でcloseされます。しかし、issueがopenされた後にアクティブでなくなったり、issueが90日以上openのままである場合もあります。

特別な種類のissueに対処する

SIG Docsでは、対処方法をドキュメントに書いても良いくらい頻繁に、以下のような種類のissueに出会います。

重服したissue

1つの問題に対して1つ以上のissueがopenしている場合、1つのissueに統合します。あなたはどちらのissueをopenにしておくか(あるいは新しいissueを作成するか)を決断して、すべての関連する情報を移動し、関連するすべてのissueにリンクしなければなりません。最後に、同じ問題について書かれたすべての他のissueにtriage/duplicateラベルを付けて、それらをcloseします。作業対象のissueを1つだけにすることで、混乱を減らし、同じ問題に対して作業が重複することを避けられます。

リンク切れに関するissue

リンク切れのissueがAPIまたはkubectlのドキュメントにあるものは、問題が完全に理解されるまでは/priority critical-urgentを割り当ててください。その他のすべてのリンク切れに関するissueには、手動で修正が必要であるため、/priority important-longtermを付けます。

Blogに関するissue

Kubernetes Blogのエントリーは時間が経つと情報が古くなるものだと考えています。そのため、ブログのエントリーは1年以内のものだけをメンテナンスします。1年以上前のブログエントリーに関するissueは修正せずにcloseします。

サポートリクエストまたはコードのバグレポート

一部のドキュメントのissueは、実際には元になっているコードの問題や、何か(たとえば、チュートリアル)がうまく動かないときにサポートをリクエストするものです。ドキュメントに関係のない問題は、kind/supportラベルを付け、サポートチャンネル(SlackやStack Overflowなど)へ報告者を導くコメントをして、もし関連があれば機能のバグに対するissueを報告するリポジトリ(kubernetes/kubernetesは始めるのに最適な場所です)を教えて、closeします。

サポートリクエストに対する返答の例を示します。(リクエストを行う際は英語で行うことが想定されるため、英文とその日本語訳を記載しています)

This issue sounds more like a request for support and less
like an issue specifically for docs. I encourage you to bring
your question to the `#kubernetes-users` channel in
[Kubernetes slack](https://slack.k8s.io/). You can also search
resources like
[Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes)
for answers to similar questions.

You can also open issues for Kubernetes functionality in
https://github.com/kubernetes/kubernetes.

If this is a documentation issue, please re-open this issue.

このissueは特定のドキュメントに関するissueではなく、サポートリクエストのようです。
Kubernetesに関する質問については、[Kubernetes slack](https://slack.k8s.io/)の
`#kubernetes-users`チャンネルに投稿することをおすすめします。同様の質問に対する回答を
[Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes)などの
リソースで検索することもできます。

Kubernetesの機能に関するissueについては、https://github.com/kubernetes/kubernetes
でissueを作成できます。

もしこれがドキュメントに関するissueの場合、このissueを再びopenしてください。

コードのバグに対する返答の例を示します。

This sounds more like an issue with the code than an issue with
the documentation. Please open an issue at
https://github.com/kubernetes/kubernetes/issues.

If this is a documentation issue, please re-open this issue.

こちらのissueは、ドキュメントではなくコードに関係するissueのようです。
https://github.com/kubernetes/kubernetes/issues でissueを作成してください。

もしこれがドキュメントに関するissueの場合、このissueを再びopenしてください。

4 - Kubernetesのドキュメントを翻訳する

このページでは、Kubernetesドキュメントにおける日本語翻訳の方針について説明します。

ドキュメントを日本語に翻訳するまでの流れ

翻訳を行うための基本的な流れについて説明します。不明点がある場合はKubernetes公式Slackの#kubernetes-docs-jaチャンネルにてお気軽にご質問ください。

前提知識

翻訳作業は全てGitHubのIssueによって管理されています。翻訳作業を行いたい場合は、Issueの一覧をまず最初にご確認ください。

また、Kubernetes傘下のリポジトリではCLAと呼ばれる同意書に署名しないと、Pull Requestをマージすることができません。詳しくは英語のドキュメントや、Qiitaに有志の方が書いてくださった日本語のまとめをご覧ください。

翻訳を始めるまで

翻訳を希望するページのIssueが存在しない場合

1. こちらのサンプルに従う形でIssueを作成する
2. 自分自身を翻訳作業に割り当てたい場合は、Issueのメッセージまたはコメントに/assignと書く
3. 新規ページを翻訳する場合のステップに進む

不明点がある場合はKubernetes公式Slackの#kubernetes-docs-jaチャンネルにてお気軽にご質問ください。

翻訳を希望するページのIssueが存在する場合

1. 自分自身を翻訳作業に割り当てるために、Issueのコメントに/assignと書く
2. 新規ページを翻訳する場合のステップに進む

Pull Requestを送るまで

未翻訳ページの新規翻訳作業と既存ページの修正作業でそれぞれ手順が異なります。

既存ページへの追加修正については、後述のマイルストーンについてに目を通すことをおすすめします。

新規ページを翻訳する場合の手順

1. kubernetes/websiteリポジトリをフォークする
2. masterから任意の名前でブランチを作成する
3. content/enのディレクトリから必要なファイルをcontent/jaにコピーし、翻訳する
4. masterブランチに向けてPull Requestを作成する

既存のページの誤字脱字や古い記述を修正する場合の手順

1. kubernetes/websiteリポジトリをフォークする
2. dev-1.18-ja.2(最新のマイルストーンブランチに適宜読み替えること)から任意の名前でブランチを作成し、該当箇所を編集する
3. dev-1.18-ja.2(最新のマイルストーンブランチに適宜読み替えること)ブランチに向けてPull Requestを作成する

マイルストーンについて

翻訳作業を集中的に管理するために、日本語を含む複数の言語ではマイルストーンを採用しています。

各マイルストーンでは、

• 最低要件のコンテンツの追加・更新(項目についてはこちらを参照してください)
• バージョンに追従できていない翻訳済みコンテンツの更新

を行い、ドキュメントの全体的なメンテナンスを行っています。

マイルストーンのバージョンはOwner権限を持つメンバーが管理するものとします。

翻訳スタイルガイド

基本方針

• 本文を、敬体（ですます調）で統一
  • 特に、「〜になります」「〜となります」という表現は「〜です」の方が適切な場合が多いため注意
• 句読点は「、」と「。」を使用
• 漢字、ひらがな、カタカナは全角で表記
• 数字とアルファベットは半角で表記
• スペースと括弧 () 、コロン : は半角、それ以外の記号類は全角で表記
• 英単語と日本語の間に半角スペースは不要

頻出単語

備考

ServiceやDeploymentなどのKubernetesのAPIオブジェクトや技術仕様的な固有名詞は、無理に日本語訳せずそのまま書いてください。

また、日本語では名詞を複数形にする意味はあまりないので、英語の名詞を利用する場合は原則として単数形で表現してください。

例:

• Kubernetes Service
• Node
• Pod

外部サイトへの参照の記事タイトルは翻訳しましょう。(一時的)

頻出表記（日本語）

単語末尾に長音記号(「ー」)を付けるかどうか

「サーバー」「ユーザー」など英単語をカタカナに訳すときに、末尾の「ー」を付けるかどうか。

• 「r」「re」「y」などで終わる単語については、原則付ける
• 上の頻出語のように、別途まとめたものは例外とする

参考: https://kubernetes.slack.com/archives/CAG2M83S8/p1554096635015200 辺りのやりとり

cron jobの訳し方に関して

混同を避けるため、cron jobはcronジョブと訳し、CronJobはリソース名としてのままにする。 cron「の」ジョブは、「の」が続く事による解釈の難から基本的にはつけないものとする。

その他基本方針など

• 意訳と直訳で迷った場合は「直訳」で訳す
• 訳で難しい・わからないと感じたらSlackの#kubernetes-docs-jaでみんなに聞く
• できることを挙手制で、できないときは早めに報告

アップストリームのコントリビューター

SIG Docsでは、英語のソースに対するアップストリームへのコントリビュートや誤りの訂正を歓迎しています。

5 - SIG Docsへの参加

SIG Docsは、Kubernetesプロジェクト内の special interest groupsの1つであり、 Kubernetes全体のドキュメントの作成、更新、および保守に重点を置いています。 SIGの詳細については、SIG DocsのGithubリポジトリを参照してください。

SIG Docsは、すべての寄稿者からのコンテンツとレビューを歓迎します。 誰でもPull Request(PR)を開くことができ、コンテンツに関するissueを提出したり、進行中のPull Requestにコメントしたりできます。

あなたは、memberや、 reviewer、 approverになることもできます。 これらの役割にはより多くのアクセスが必要であり、変更を承認およびコミットするための特定の責任が伴います。 Kubernetesコミュニティ内でメンバーシップがどのように機能するかについての詳細は、 community-membership をご覧ください。

このドキュメントの残りの部分では、kubernetesの中で最も広く公開されている Kubernetesのウェブサイトとドキュメントの管理を担当しているSIG Docsの中で、これらの役割がどのように機能するのかを概説します。

SIG Docs chairperson

SIG Docsを含む各SIGは、議長として機能する1人以上のSIGメンバーを選択します。 これらは、SIGDocsとKubernetes organizationの他の部分との連絡先です。 それらには、Kubernetesプロジェクト全体の構造と、SIG Docsがその中でどのように機能するかについての広範な知識が必要です。 現在のchairpersonのリストについては、 Leadership を参照してください。

SIG Docs teamsと自動化

SIG Docsの自動化は、GitHub teamsとOWNERSファイルの2つの異なるメカニズムに依存しています。

GitHub teams

GitHubには、二つのSIG Docs teams カテゴリがあります:

• @sig-docs-{language}-ownersは承認者かつリードです。
• @sig-docs-{language}-reviews はレビュアーです。

それぞれをGitHubコメントの@nameで参照して、そのグループの全員とコミュニケーションできます。

ProwチームとGitHub teamsが完全に一致せずに重複する場合があります。 問題の割り当て、Pull Request、およびPR承認のサポートのために、自動化ではOWNERSファイルからの情報を使用します。

OWNERSファイルとfront-matter

Kubernetesプロジェクトは、GitHubのissueとPull Requestに関連する自動化のためにprowと呼ばれる自動化ツールを使用します。 Kubernetes Webサイトリポジトリ は、2つのprowプラグインを使用します：

• blunderbuss
• approve

これらの2つのプラグインはkubernetes.websiteのGithubリポジトリのトップレベルにある OWNERSファイルと、 OWNERS_ALIASESファイルを使用して、 リポジトリ内でのprowの動作を制御します。

OWNERSファイルには、SIG Docsのレビュー担当者および承認者であるユーザーのリストが含まれています。 OWNERSファイルはサブディレクトリに存在することもでき、そのサブディレクトリとその子孫のファイルのレビュー担当者または承認者として機能できるユーザーを上書きできます。 一般的なOWNERSファイルの詳細については、 OWNERSを参照してください。

さらに、個々のMarkdownファイルは、個々のGitHubユーザー名またはGitHubグループを一覧表示することにより、そのfront-matterでレビュー担当者と承認者を一覧表示できます。

OWNERSファイルとMarkdownファイルのfront-matterの組み合わせにより、PRの技術的および編集上のレビューを誰に依頼するかについてPRの所有者が自動化システムから得るアドバイスが決まります。

マージの仕組み

Pull Requestがコンテンツの公開に使用されるブランチにマージされると、そのコンテンツは http://kubernetes.io に公開されます。 公開されたコンテンツの品質を高くするために、Pull RequestのマージはSIG Docsの承認者に限定しています。仕組みは次のとおりです。

• Pull Requestにlgtmラベルとapproveラベルの両方があり、holdラベルがなく、すべてのテストに合格すると、Pull Requestは自動的にマージされます。
• Kubernetes organizationのメンバーとSIG Docsの承認者はコメントを追加して、特定のPull Requestが自動的にマージされないようにすることができます(/holdコメントを追加するか、/lgtmコメントを保留します)。
• Kubernetesメンバーは誰でも、/lgtmコメントを追加することでlgtmラベルを追加できます。
• /approveコメントを追加してPull Requestをマージできるのは、SIG Docsの承認者だけです。一部の承認者は、PR WranglerやSIG Docsのchairpersonなど、追加の特定の役割も実行します。

次の項目

Kubernetesドキュメントへの貢献の詳細については、以下を参照してください：

• Contributing new content
• Reviewing content
• ドキュメントスタイルの概要

6 - ドキュメントスタイルの概要

このセクション内のトピックでは、文章のスタイル、コンテンツの形式や構成、特にKubernetesのドキュメント特有のHugoカスタマイズの使用方法に関するガイダンスを提供します。

6.1 - ドキュメントコンテンツガイド

このページでは、Kubernetesのドキュメント上のコンテンツのガイドラインを説明します。

許可されるコンテンツに関して疑問がある場合は、Kubernetes Slackの#sig-docsチャンネルに参加して質問してください！

Kubernetes Slackには、https://slack.k8s.io/ から参加登録ができます。

Kubernetesドキュメントの新しいコンテンツの作成に関する情報については、スタイルガイドに従ってください。

概要

ドキュメントを含むKubernetesのウェブサイトのソースは、kubernetes/websiteリポジトリに置かれています。

Kubernetesの主要なドキュメントはkubernetes/website/content/<language_code>/docsフォルダに置かれており、これらはKubernetesプロジェクトを対象としています。

許可されるコンテンツ

Kubernetesのドキュメントにサードパーティーのコンテンツを掲載することが許されるのは、次の場合のみです。

• コンテンツがKubernetesプロジェクト内のソフトウェアのドキュメントとなる場合
• コンテンツがプロジェクト外のソフトウェアのドキュメントとなるが、Kubernetesを機能させるために必要である場合
• コンテンツがkubernetes.ioの正規のコンテンツであるか、他の場所の正規のコンテンツへのリンクである場合

サードパーティーのコンテンツ

Kubernetesのドキュメントには、Kubernetesプロジェクト(kubernetesおよびkubernetes-sigs GitHub organizationsに存在するプロジェクト)の適用例が含まれています。

Kubernetesプロジェクト内のアクティブなコンテンツへのリンクは常に許可されます。

Kubernetesを機能させるためには、一部サードパーティーのコンテンツが必要です。たとえば、コンテナランタイム(containerd、CRI-O、Docker)、ネットワークポリシー(CNI plugin)、Ingressコントローラー、ロギングなどです。

ドキュメント内で、Kubernetesプロジェクト外のサードパーティーのオープンソースソフトウェア(OSS)にリンクすることができるのは、Kubernetesを機能させるために必要な場合のみです。

情報源が重複するコンテンツ

可能な限り、Kubernetesのドキュメントは正規の情報源にリンクするようにし、情報源が重複してしまうようなホスティングは行いません。

情報源が重複したコンテンツは、メンテナンスするために2倍の労力(あるいはそれ以上！)が必要になり、より早く情報が古くなってしまいます。

その他の情報

許可されるコンテンツに関して疑問がある場合は、Kubernetes Slackの#sig-docsチャンネルに参加して質問してください！

次の項目

• スタイルガイドを読む

6.2 - コンテンツの構造化

このサイトではHugoを使用しています。Hugoでは、コンテンツの構造化がコアコンセプトとなっています。

ページの一覧

ページの順序

ドキュメントのサイドメニューやページブラウザーなどでは、Hugoのデフォルトのソート順序を使用して一覧を作成しています。デフォルトでは、weight(1から開始)、日付(最新のものが1番目)、最後にリンクのタイトルの順でソートされます。

そのため、特定のページやセッションを上に移動したい場合には、ページのフロントマター内のweightを設定します。

title: My Page
weight: 10

ドキュメントのメインメニュー

ドキュメントのメインメニューは、docs/以下に置かれたセクションのコンテンツファイル_index.mdのフロントマター内にmain_menuフラグが設定されたものから生成されます。

main_menu: true

リンクのタイトルは、ページのlinkTitleから取得されることに注意してください。そのため、ページのタイトルとは異なるリンクテキストにしたい場合、コンテンツファイル内の値を以下のように設定します。

main_menu: true
title: ページタイトル
linkTitle: リンク内で使われるタイトル

ドキュメントのサイドメニュー

ドキュメントのサイドバーメニューは、docs/以下の現在のセクションツリーから生成されます。

セクションと、そのセクション内のページがすべて表示されます。

特定のセクションやページをリストに表示したくない場合、フロントマター内のtoc_hideフラグをtrueに設定してください。

toc_hide: true

コンテンツが存在するセクションに移動すると、特定のセクションまたはページ(例:index.md)が表示されます。それ以外の場合、そのセクションの最初のページが表示されます。

ドキュメントのブラウザー

ドキュメントのホームページのページブラウザーは、docsセクション直下のすべてのセクションとページを使用して生成されています。

特定のセクションやページを表示したくない場合、フロントマターのtoc_hideフラグをtrueに設定してください。

toc_hide: true

メインメニュー

右上のメニュー(およびフッター)にあるサイトリンクは、page-lookupの機能を使用して実装されています。これにより、ページが実際に存在することを保証しています。そのため、たとえばcase-studiesのセクションが特定の言語のサイトに存在しない場合、メニューにはケーススタディのリンクが表示されません。

Page Bundle

スタンドアローンのコンテンツページ(Markdownファイル)に加えて、Hugoでは、Page Bundlesがサポートされています。

Page Bundleの1つの例は、カスタムのHugo Shortcodeです。これは、leaf bundleであると見做されます。ディレクトリ内のすべてのファイルは、index.mdを含めてバンドルの一部となります。これには、ページからの相対リンク、処理可能な画像なども含まれます。

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

もう1つのPage Bundleがよく使われる例は、includesバンドルです。フロントマターにheadless: trueを設定すると、自分自身のURLを持たなくなり、他のページ内でのみ使用されるようになります。

en/includes
├── default-storage-class-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

バンドル内のファイルに関して、いくつか重要な注意点があります。

• 翻訳されたバンドルに対しては、コンテンツ以外の見つからなかったファイルは上位の言語から継承されます。これにより重複が回避できます。
• バンドル内のすべてのファイルは、HugoがResourcesと呼ぶファイルになり、フロントマター(YAMLファイルなど)をサポートしていない場合であっても、言語ごとにパラメーターやタイトルなどのメタデータを提供できます。詳しくは、Page Resourcesメタデータを参照してください。
• Resourceの.RelPermalinkから取得した値は、ページからの相対的なものとなっています。詳しくは、Permalinksを参照してください。

スタイル

このサイトのスタイルシートのSASSのソースは、assets/sassに置かれていて、Hugoによって自動的にビルドされます。

次の項目

• カスタムのHugo shortcodeについて学ぶ
• スタイルガイドについて学ぶ
• コンテンツガイドについて学ぶ

6.3 - カスタムHugoショートコード

このページではKubernetesのマークダウンドキュメント内で使用できるHugoショートコードについて説明します。

ショートコードについての詳細はHugoのドキュメントを読んでください。

機能の状態

このサイトのマークダウンページ(.mdファイル)内では、説明されている機能のバージョンや状態を表示するためにショートコードを使用することができます。

機能の状態のデモ

最新のKubernetesバージョンで機能をstableとして表示するためのデモスニペットを次に示します。

{{< feature-state state="stable" >}}

これは次の様に表示されます:

stateの値として妥当な値は次のいずれかです:

• alpha
• beta
• deprecated
• stable

機能の状態コード

表示されるKubernetesのバージョンのデフォルトはそのページのデフォルトまたはサイトのデフォルトです。 for_k8s_versionパラメーターを渡すことにより、機能の状態バージョンを変更することができます。 例えば:

{{< feature-state for_k8s_version="v1.10" state="beta" >}}

これは次の様に表示されます:

用語集

用語集に関連するショートコードとして、glossary_tooltipとglossary_definitionの二つがあります。

コンテンツを自動的に更新し、用語集へのリンクを付与する挿入を使用して、用語を参照することができます。 用語がマウスオーバーされると、用語集の内容がツールチップとして表示されます。 また、用語はリンクとして表示されます。

ツールチップの挿入と同様に、用語集の定義も再利用することができます。

用語集の用語データはglossaryディレクトリに、それぞれの用語のファイルとして保存されています。

用語集のデモ

例えば、マークダウン内でツールチップ付きのclusterを表示するには、次の挿入を使用します:

{{< glossary_tooltip text="cluster" term_id="cluster" >}}

用語集の定義はこのようにします:

{{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}}

これは次の様に表示されます:

A cluster is コンテナ化されたアプリケーションを実行する、ノードと呼ばれるワーカーマシンの集合です。すべてのクラスターには少なくとも1つのワーカーノードがあります。

完全な用語定義を挿入することもできます:

{{< glossary_definition term_id="cluster" length="all" >}}

これは次の様に表示されます:

コンテナ化されたアプリケーションを実行する、ノードと呼ばれるワーカーマシンの集合です。すべてのクラスターには少なくとも1つのワーカーノードがあります。

ワーカーノードは、アプリケーションのコンポーネントであるPodをホストします。マスターノードは、クラスター内のワーカーノードとPodを管理します。複数のマスターノードを使用して、クラスターにフェイルオーバーと高可用性を提供します。 ワーカーノードは、アプリケーションワークロードのコンポーネントであるPodをホストします。コントロールプレーンは、クラスター内のワーカーノードとPodを管理します。本番環境では、コントロールプレーンは複数のコンピューターを使用し、クラスターは複数のノードを使用し、耐障害性や高可用性を提供します。

APIリファレンスへのリンク

api-referenceショートコードを使用することで、Kubernetes APIリファレンスへのリンクを作成することができます。 例えば、 Podへの参照方法は次の通りです:

{{< api-reference page="workload-resources/pod-v1" >}}

pageパラメーターの値はAPIリファレンスページのURLの末尾です。

anchorパラメーターを指定することでページ内の特定の場所へリンクすることもできます。 例えば、 PodSpecや environment-variablesへのリンクは次の様に書きます:

{{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}}
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}

textパラメーターを指定することでリンクテキストを変更することもできます。 例えば、 Environment Variablesへのリンクは次の様に書きます:

{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variable" >}}

テーブルキャプション

テーブルキャプションを追加することで、表をスクリーンリーダーにとってよりアクセスしやすいものにする事ができます。 表へキャプションを追加するには、表をtableショートコードで囲い、captionパラメーターにキャプションを指定します。

例えば、次の様に書きます:

{{< table caption="Configuration parameters" >}}
Parameter | Description | Default
:---------|:------------|:-------
`timeout` | The timeout for requests | `30s`
`logLevel` | The log level for log output | `INFO`
{{< /table >}}

これは次の様に表示されます:

この表に対するHTMLを検査すると、次の要素が<table>要素のすぐ次にあるのを見ることができるでしょう:

<caption style="display: none;">Configuration parameters</caption>

タブ

このサイトのマークダウンページ(.mdファイル)内では、あるソリューションに対する複数のフレーバーを表示するためのタブセットを追加することができます。

tabsショートコードはこれらのパラメーターを受けとります:

• name: タブに表示される名前
• codelang: 内側のtabショートコードにこれを指定した場合、Hugoはハイライトに使用するコード言語を知ることができます。
• include: タブ内で挿入するファイル。Hugo leaf bundle内にタブがある場合そのファイル(HugoがサポートしているどのMIMEタイプでも良い)はそのbundle自身によって探されます。 もしそうでない場合、そのコンテントページは現在のページから相対的に探されます。 includeを使う場合、ショートコードの内部コンテンツはなく、自己終了構文を使用する必要があることに注意してください。 例えば、{{< tab name="Content File #1" include="example1" />}}の様にします。 codelangを指定するか、ファイル名から言語が特定される必要があります。 非コンテンツファイルはデフォルトでコードが強調表示されます。
• もし内部コンテンツがマークダウンの場合、タブの周りに%デリミターを使用する必要があります。 例えば、{{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}の様にします。
• タブセット内で、上記で説明したバリエーションを組み合わせることができます。

タブショートコードの例を次に示します。

タブのデモ: コードハイライト

{{< tabs name="tab_with_code" >}}
{{{< tab name="Tab 1" codelang="bash" >}}
echo "これはタブ1です。"
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "これはタブ2です。"
{{< /tab >}}}
{{< /tabs >}}

これは次の様に表示されます:

• Tab 1
• Tab 2

echo "これはタブ1です。"

println "これはタブ2です。"

タブのデモ: インラインマークダウンとHTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
これは**なにがしかのマークダウン**です。
{{< note >}}
ショートコードを含むこともできます。
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>プレーンHTML</h3>
	<p>これはなにがしかの<i>プレーン</i>HTMLです。</p>
</div>
{{< /tab >}}
{{< /tabs >}}

これは次の様に表示されます。

• Markdown
• HTML

タブのデモ: ファイルの読み込み

{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}

これは次の様に表示されます:

• Content File #1
• Content File #2
• JSON File

  {
    "apiVersion": "v1",
    "kind": "PodTemplate",
    "metadata": {
      "name": "nginx"
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "nginx"
        },
        "generateName": "nginx-"
      },
      "spec": {
         "containers": [{
           "name": "nginx",
           "image": "dockerfile/nginx",
           "ports": [{"containerPort": 80}]
         }]
      }
    }
  }

サードパーティーコンテンツマーカー

Kubernetesの実行にはサードパーティーのソフトウェアが必要です。 例えば、名前解決を行うためにはクラスターにDNSサーバーを追加する必要があります。

私たちがサードパーティーソフトウェアにリンクするときや言及するときは、コンテンツガイドに従い、サードパーティーのものに印をつけます。

これらのショートコードを使用すると、それらを使用しているドキュメントページに免責事項が追加されます。

リスト

サードパーティーのリストには、

{{% thirdparty-content %}}

をすべてのアイテムを含むセクションのヘッダーのすぐ下に追加します。

アイテム

ほとんどのアイテムがプロジェクト内ソフトウェア(例えばKubernetes自体やDeschedulerコンポーネント)を参照している場合、違う形を使用することができます。

次のショートコードをアイテムの前か、特定のアイテムのヘッダーのすぐ下に追加します:

{{% thirdparty-content single="true" %}}

バージョン文字列

ドキュメント内でバージョン文字列を生成して挿入するために、いくつかのバージョンショートコードから選んで使用することができます。 それぞれのバージョンショートコードはサイトの設定ファイル(hugo.toml)から取得したバージョンパラメーターの値を使用してバージョン文字列を表示します。 最もよく使われる二つのバージョンパラメーターはlatestとversionです。

{{< param "version" >}}

{{< param "version" >}}ショートコードはサイトのversionパラメーターに設定されたKubernetesドキュメントの現在のバージョンを生成します。 paramショートコードはサイトパラメーターの名前の一つを受けとり、この場合はversionを渡しています。

これは次の様に表示されます:

{{< latest-version >}}

{{< latest-version >}}ショートコードはサイトのlatestパラメーターの値を返します。 サイトのlatestパラメーターは新しいドキュメントのバージョンがリリースされた時に更新されます。 このパラメーターは必ずしもversionの値と一致しません。

これは次の様に表示されます:

{{< latest-semver >}}

{{< latest-semver >}}ショートコードはlatestから"v"接頭辞を取り除いた値を生成します。

これは次の様に表示されます。

{{< version-check >}}

{{< version-check >}}ショートコードはページにmin-kubernetes-server-versionパラメーターがあるかどうか確認し、versionと比較するために使用します。

これは次の様に表示されます:

{{< latest-release-notes >}}

{{< latest-release-notes >}}ショートコードはlatestからバージョン文字列を生成し、"v"接頭辞を取り除きます。 このショートコードはバージョン文字列に対応したリリースノートCHANGELOGページのURLを表示します。

これは次の様に表示されます:

次の項目

• Hugoについて学ぶ。
• 新しいトピックの書き方について学ぶ。
• ページコンテンツタイプについて学ぶ。
• Pull Requestの作り方について学ぶ。
• 発展的コントリビュートについて学ぶ。