Contribute to Kubernetes docs

Edit This Page

Start contributing

If you want to get started contributing to the Kubernetes documentation, this page and its linked topics can help you get started. You don’t need to be a developer or a technical writer to make a big impact on the Kubernetes documentation and user experience! All you need for the topics on this page is a Github account and a web browser.

If you’re looking for information on how to start contributing to Kubernetes code repositories, refer to the Kubernetes community guidelines.

The basics about our docs

The Kubernetes documentation is written in Markdown and processed and deployed using Hugo. The source is in Github at https://github.com/kubernetes/website. Most of the documentation source is stored in /content/en/docs/. Some of the reference documentation is automatically generated from scripts in the update-imported-docs/ directory.

You can file issues, edit content, and review changes from others, all from the Github website. You can also use Github’s embedded history and search tools.

Not all tasks can be done in the Github UI, but these are discussed in the intermediate and advanced docs contribution guides.

Participating in SIG Docs

The Kubernetes documentation is maintained by a Special Interest Group (SIG) called SIG Docs. We communicate using a Slack channel, a mailing list, and weekly video meetings. New participants are welcome. For more information, see Participating in SIG Docs.

Style guidelines

We maintain a style guide with information about choices the SIG Docs community has made about grammar, syntax, source formatting, and typographic conventions. Look over the style guide before you make your first contribution, and use it when you have questions.

Changes to the style guide are made by SIG Docs as a group. To propose a change or addition, add it to the agenda for an upcoming SIG Docs meeting, and attend the meeting to participate in the discussion. See the advanced contribution topic for more information.

Page templates

We use page templates to control the presentation of our documentation pages. Be sure to understand how these templates work by reviewing Using page templates.

Hugo shortcodes

The Kubernetes documentation is transformed from Markdown to HTML using Hugo. We make use of the standard Hugo shortcodes, as well as a few that are custom to the Kubernetes documentation. See Custom Hugo shortcodes for information about how to use them.

Multiple languages

Documentation source is available in multiple languages in /content/. Each language has its own folder with a two-letter code determined by the ISO 639-1 standard. For example, English documentation source is stored in /content/en/docs/.

For more information about contributing to documentation in multiple languages, see “Localize content” in the intermediate contributing guide.

If you’re interested in starting a new localization, see “Localization”.

File actionable issues

Anyone with a Github account can file an issue (bug report) against the Kubernetes documentation. If you see something wrong, even if you have no idea how to fix it, file an issue. The exception to this rule is a tiny bug like a typo that you intend to fix yourself. In that case, you can instead fix it without filing a bug first.

How to file an issue

How to file great issues

To ensure that we understand your issue and can act on it, keep these guidelines in mind:

Participate in SIG Docs discussions

The SIG Docs team communicates using the following mechanisms:

Note: You can also check the SIG Docs weekly meeting on the Kubernetes community meetings calendar.

Improve existing content

To improve existing content, you file a pull request (PR) after creating a fork. Those two terms are specific to Github. For the purposes of this topic, you don’t need to know everything about them, because you can do everything using your web browser. When you continue to the intermediate docs contributor guide, you will need more background in Git terminology.

Note: Kubernetes code developers: If you are documenting a new feature for an upcoming Kubernetes release, your process is a bit different. See Document a feature for process guidelines and information about deadlines.

Sign the CLA

Before you can contribute code or documentation to Kubernetes, you must read the Contributor guide and sign the Contributor License Agreement (CLA). Don’t worry – this doesn’t take long!

Find something to work on

If you see something you want to fix right away, just follow the instructions below. You don’t need to file an issue (although you certainly can).

If you want to start by finding an existing issue to work on, go to https://github.com/kubernetes/website/issues and look for issues with the label good first issue (you can use this shortcut). Read through the comments and make sure there is not an open pull request against the issue and that nobody has left a comment saying they are working on the issue recently (3 days is a good rule). Leave a comment saying that you would like to work on the issue.

Choose which Git branch to use

The most important aspect of submitting pull requests is choosing which branch to base your work on. Use these guidelines to make the decision:

If you’re still not sure which branch to choose, ask in #sig-docs on Slack or attend a weekly SIG Docs meeting to get clarity.

Submit a pull request

Follow these steps to submit a pull request to improve the Kubernetes documentation.

  1. On the page where you see the issue, click the pencil icon at the top left. A new page appears, with some help text.

  2. Click the first blue button, which has the text Edit <page name>.

    If you have never created a fork of the Kubernetes documentation repository, you are prompted to do so. Create the fork under your Github username, rather than another organization you may be a member of. The fork usually has a URL such as https://github.com/<username>/website, unless you already have a repository with a conflicting name.

    The reason you are prompted to create a fork is that you do not have access to push a branch directly to the definitive Kubernetes repository.

  3. The Github Markdown editor appears with the source Markdown file loaded. Make your changes. Below the editor, fill in the Propose file change form. The first field is the summary of your commit message and should be no more than 50 characters long. The second field is optional, but can include more detail if appropriate.

    Note: Do not include references to other Github issues or pull requests in your commit message. You can add those to the pull request description later.

    Click Propose file change. The change is saved as a commit in a new branch in your fork, which is automatically named something like patch-1.

  4. The next screen summarizes the changes you made, by comparing your new branch (the head fork and compare selection boxes) to the current state of the base fork and base branch (master on the kubernetes/website repository by default). You can change any of the selection boxes, but don’t do that now. Have a look at the difference viewer on the bottom of the screen, and if everything looks right, click Create pull request.

    Note: If you don’t want to create the pull request now, you can do it later, by browsing to the main URL of the Kubernetes website repository or your fork’s repository. The Github website will prompt you to create the pull request if it detects that you pushed a new branch to your fork.

  5. The Open a pull request screen appears. The subject of the pull request is the same as the commit summary, but you can change it if needed. The body is populated by your extended commit message (if present) and some template text. Read the template text and fill out the details it asks for, then delete the extra template text. Leave the Allow edits from maintainers checkbox selected. Click Create pull request.

    Congratulations! Your pull request is available in Pull requests.

    After a few minutes, you can preview the website with your PR’s changes applied. Go to the Conversation tab of your PR and click the Details link for the deploy/netlify test, near the bottom of the page. It opens in the same browser window by default.

  6. Wait for review. Generally, reviewers are suggested by the k8s-ci-robot. If a reviewer asks you to make changes, you can go to the Files changed tab and click the pencil icon on any files that have been changed by the pull request. When you save the changed file, a new commit is created in the branch being monitored by the pull request.

  7. If your change is accepted, a reviewer merges your pull request, and the change is live on the Kubernetes website a few minutes later.

This is only one way to submit a pull request. If you are already a Git and Github advanced user, you can use a local GUI or command-line Git client instead of using the Github UI. Some basics about using the command-line Git client are discussed in the intermediate docs contribution guide.

Review docs pull requests

People who are not yet approvers or reviewers can still review pull requests. The reviews are not considered “binding”, which means that your review alone won’t cause a pull request to be merged. However, it can still be helpful. Even if you don’t leave any review comments, you can get a sense of pull request conventions and etiquette and get used to the workflow.

  1. Go to https://github.com/kubernetes/website/pulls. You see a list of every open pull request against the Kubernetes website and docs.

  2. By default, the only filter that is applied is open, so you don’t see pull requests that have already been closed or merged. It’s a good idea to apply the cncf-cla: yes filter, and for your first review, it’s a good idea to add size/S or size/XS. The size label is applied automatically based on how many lines of code the PR modifies. You can apply filters using the selection boxes at the top of the page, or use this shortcut for only small PRs. All filters are ANDed together, so you can’t search for both size/XS and size/S in the same query.

  3. Go to the Files changed tab. Look through the changes introduced in the PR, and if applicable, also look at any linked issues. If you see a problem or room for improvement, hover over the line and click the + symbol that appears.

    You can type a comment, and either choose Add single comment or Start a review. Typically, starting a review is better because it allows you to leave multiple comments and notifies the PR owner only when you have completed the review, rather than a separate notification for each comment.

  4. When finished, click Review changes at the top of the page. You can summarize your review, and you can choose to comment, approve, or request changes. New contributors should always choose Comment.

Thanks for reviewing a pull request! When you are new to the project, it’s a good idea to ask for feedback on your pull request reviews. The #sig-docs Slack channel is a great place to do this.

Write a blog post

Anyone can write a blog post and submit it for review. Blog posts should not be commercial in nature and should consist of content that will apply broadly to the Kubernetes community.

To submit a blog post, you can either submit it using the Kubernetes blog submission form, or follow the steps below.

  1. Sign the CLA if you have not yet done so.
  2. Have a look at the Markdown format for existing blog posts in the website repository.
  3. Write out your blog post in a text editor of your choice.
  4. On the same link from step 2, click the Create new file button. Paste your content into the editor. Name the file to match the proposed title of the blog post, but don’t put the date in the file name. The blog reviewers will work with you on the final file name and the date the blog will be published.
  5. When you save the file, Github will walk you through the pull request process.
  6. A blog post reviewer will review your submission and work with you on feedback and final details. When the blog post is approved, the blog will be scheduled for publication.

Submit a case study

Case studies highlight how organizations are using Kubernetes to solve real-world problems. They are written in collaboration with the Kubernetes marketing team, which is handled by the CNCF.

Have a look at the source for the existing case studies. Use the Kubernetes case study submission form to submit your proposal.

What's next

When you are comfortable with all of the tasks discussed in this topic and you want to engage with the Kubernetes docs team in deeper ways, read the intermediate docs contribution guide.

Feedback