This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

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

ドキュメントやウェブサイトに貢献したい方、ご協力お待ちしています。 はじめての方、久しぶりの方、開発者でもエンドユーザでも、はたまたタイポを見逃せない方でもどなたでも貢献可能です。

はじめに

どなたでも、問題を説明するissueや、ドキュメントの改善を求めるissueを作成し、プルリクエスト(PR)を用いて変更に貢献することができます。 一部のタスクでは、Kubernetes organizationで、より多くの信頼とアクセス権限が必要です。 役割と権限についての詳細は、SIG Docsへの参加を参照してください。

Kubernetesのドキュメントは、GitHubのリポジトリーにあります。 どなたからの貢献も歓迎しますが、Kubernetesコミュニティの効果的な運用のためには、gitとGitHubを基本的に使いこなせる必要があります。

ドキュメンテーションに関わるには:

  1. CNCFのContributor License Agreementにサインしてください。
  2. ドキュメンテーションのリポジトリーと、ウェブサイトの静的サイトジェネレーターに慣れ親しんでください。
  3. コンテンツの改善と変更レビューの基本的なプロセスを理解していることを確認してください。

貢献するためのベストプラクティス

  • 明快で意味のあるGitコミットメッセージを書いてください。
  • PRがマージされたときにissueを参照し、自動的にissueをクローズする Github Special Keywords を必ず含めるようにしてください。
  • タイプミスの修正や、スタイルの変更、文法の変更などのような小さな変更をPRに加える場合は、比較的小さな変更のためにコミットの数が増えすぎないように、コミットはまとめてください。
  • あなたがコードを変更をした理由を示し、レビュアーがあなたのPRを理解するのに十分な情報を確保した適切なPR説明を、必ず含めるようにしてください。
  • 追加文献 :

その他の貢献方法

次の項目

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 - 変更のレビュー

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

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

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

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

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

はじめる前に

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

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

レビューのプロセス

一般に、コンテンツや文体に対するプルリクエストは、英語でレビューを行います。

  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セクションまでスクロールし、deploy/netlifyの行のDetailsリンクをクリックして、Netlifyのプレビュービルドで変更点をプレビューします。

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

    1. コメントしたい場合は行の横の+マークをクリックします。
    2. その行に関するコメントを書き、Add single comment(1つのコメントだけを残したい場合)またはStart a review(複数のコメントを行いたい場合)のいずれかをクリックします。
    3. コメントをすべて書いたら、ページ上部のReview changesをクリックします。ここでは、レビューの要約を追加できます(コントリビューターにポジティブなコメントも書きましょう！)。必要に応じて、PRを承認したり、コメントしたり、変更をリクエストします。新しいコントリビューターの場合はCommentだけが行えます。

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

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

言語と文法

  • 言語や文法に明らかな間違いはないですか？ もっとよい言い方はないですか？
  • もっと簡単な単語に置き換えられる複雑な単語や古い単語はありませんか？
  • 使われている単語や専門用語や言い回しで差別的ではない別の言葉に置き換えられるものはありませんか？
  • 言葉選びや大文字の使い方はstyle guideに従っていますか？
  • もっと短くしたり単純な文に書き換えられる長い文はありませんか？
  • 箇条書きやテーブルでもっとわかりやすく表現できる長いパラグラフはありませんか？

コンテンツ

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

ウェブサイト

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

その他

PRに関して誤字や空白などの小さな問題を指摘する場合は、コメントの前にnit:と書いてください。こうすることで、PRの作者は問題が深刻なものではないことが分かります。

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

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

3.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のプロジェクトのメンテナーであり、ドキュメントのホスティングに関して手助けが必要なときは、Kubernetes Slackの#sig-docsで教えてください。

その他の情報

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

次の項目

3.2 - コンテンツの構造化

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

備考: Hugoのヒント: コンテンツの編集を始めるときは、hugo server --navigateToChangedコマンドを使用してHugoを実行してください。

ページの一覧

ページの順序

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

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

title: My Page
weight: 10
備考: ページのweightについては、1、2、3…などの値を使用せず、10、20、30…のように一定の間隔を空けた方が賢明です。こうすることで、後で別のページを間に挿入できるようになります。

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

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

main_menu: true

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

main_menu: true
title: ページタイトル
linkTitle: リンク内で使われるタイトル
備考: 上記の設定は言語ごとに行う必要があります。メニュー上にセクションが表示されないときは、Hugoからセクションとして認識されていないためである可能性が高いです。セクションフォルダー内に_index.mdコンテンツファイルを作成してください。

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

ドキュメントのサイドバーメニューは、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によって自動的にビルドされます。

次の項目

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権限を持つメンバーが管理するものとします。

翻訳スタイルガイド

基本方針

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

頻出単語

英語日本語
Addon/Add-onアドオン
Aggregation Layerアグリゲーションレイヤー
architectureアーキテクチャ
binaryバイナリ
clusterクラスター
communityコミュニティ
containerコンテナ
controllerコントローラー
Deployment/DeployKubernetesリソースとしてのDeploymentはママ表記、一般的な用語としてのdeployの場合は、デプロイ
directoryディレクトリ
For more informationさらなる情報(一時的)
GitHubGitHub (ママ表記)
IssueIssue (ママ表記)
operatorオペレーター
orchestrate(動詞)オーケストレーションする
Persistent VolumeKubernetesリソースとしてのPersistentVolumeはママ表記、一般的な用語としての場合は、永続ボリューム
prefixプレフィックス
Pull RequestPull Request (ママ表記)
Quotaクォータ
registryレジストリ
secureセキュア
a set of ~～の集合
stacked積層(例: stacked etcd clusterは積層etcdクラスター)

備考

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では、英語のソースに対するアップストリームへのコントリビュートや誤りの訂正を歓迎しています。