Browse files

Reorganize docs contrib guide (#9510)

* Reorganize docs contrib guide

* Address first round of feedback from Brad, Jared

* Standardize on 'SIG Docs'

* Address more feedback

* Rewrites to

* Tweak navigation titles

* Document PR Wrangler

* Document SIG Docs chairperson

* Fix codeblock that shows how to use <codenew>

It was being interpreted as a Hugo shortcode.
  • Loading branch information...
mistyhacks authored and k8s-ci-robot committed Aug 6, 2018
1 parent 4920a51 commit 5ae0d0dd8d4056360e7d66efc8d8d40b6a545629
Showing with 1,891 additions and 860 deletions.
  1. +1 −0 .github/
  2. +4 −1 .github/
  3. +4 −7
  4. +73 −0 content/en/docs/contribute/
  5. +87 −0 content/en/docs/contribute/
  6. +9 −0 content/en/docs/contribute/generate-ref-docs/
  7. 0 ...nt/en/docs/{home/contribute/generated-reference → contribute/generate-ref-docs}/
  8. 0 content/en/docs/{home/contribute/generated-reference → contribute/generate-ref-docs}/
  9. 0 ...nt/en/docs/{home/contribute/generated-reference → contribute/generate-ref-docs}/
  10. 0 ...ocs/{home/contribute/generated-reference → contribute/generate-ref-docs}/
  11. +789 −0 content/en/docs/contribute/
  12. 0 content/en/docs/{home → }/contribute/
  13. +219 −0 content/en/docs/contribute/
  14. +355 −0 content/en/docs/contribute/
  15. +9 −0 content/en/docs/contribute/style/
  16. +4 −5 content/en/docs/{home/contribute → contribute/style}/
  17. 0 content/en/docs/{home/contribute/includes → contribute/style/}/
  18. 0 content/en/docs/{home/contribute/includes → contribute/style/}/
  19. 0 content/en/docs/{home/contribute/includes → contribute/style/}/
  20. 0 content/en/docs/{home/contribute/includes → contribute/style/}/podtemplate.json
  21. +239 −0 content/en/docs/contribute/style/
  22. +7 −6 content/en/docs/{home/contribute → contribute/style}/
  23. +53 −39 content/en/docs/{home/contribute → contribute/style}/
  24. +1 −1 content/en/docs/doc-contributor-tools/snippets/
  25. +0 −65 content/en/docs/
  26. +0 −5 content/en/docs/home/contribute/
  27. +0 −134 content/en/docs/home/contribute/
  28. +0 −122 content/en/docs/home/contribute/
  29. +0 −231 content/en/docs/home/contribute/
  30. +0 −114 content/en/docs/home/contribute/
  31. +0 −104 content/en/docs/home/contribute/
  32. +1 −1 content/en/docs/reference/glossary/
  33. +0 −18 content/en/docs/reference/glossary/
  34. +10 −0 content/en/docs/
  35. +2 −4 layouts/docs/baseof.html
  36. +1 −1 layouts/docs/list.html
  37. +1 −1 layouts/partials/docs/content_page.html
  38. +22 −1 static/_redirects
@@ -1,4 +1,5 @@
<!-- Thanks for filing an issue! Before submitting, please fill in the following information. -->
<!-- See for guidance on writing an actionable issue description. -->
<!--Required Information-->
@@ -1,6 +1,9 @@
> Please delete this note before submitting the pull request.
> For 1.12 Features: set Milestone to 1.12 and Base Branch to release-1.12
> Help editing and submitting pull requests:
> Help choosing which branch to use, see
> Please delete this note before submitting the pull request.
@@ -8,13 +8,10 @@ Once your pull request is created, a Kubernetes reviewer will take responsibilit
For more information about contributing to the Kubernetes documentation, see:
* [Contributing to the Kubernetes Documentation](
* [Creating a Documentation Pull Request](
* [Writing a New Topic](
* [Review Issues](
* [Staging Your Documentation Changes](
* [Using Page Templates](
* [Documentation Style Guide](
* [Start contributing](
* [Staging Your Documentation Changes](
* [Using Page Templates](
* [Documentation Style Guide](
## Building the site using Docker
@@ -0,0 +1,73 @@
content_template: templates/concept
title: Contribute to Kubernetes docs
linktitle: Contribute
main_menu: true
weight: 80
{{% capture overview %}}
If you would like to help contribute to the Kubernetes documentation or website,
we're happy to have your help! Anyone can contribute, whether you're new to the
project or you've been around a long time, and whether you self-identify as a
developer, an end user, or someone who just can't stand seeing typos.
Looking for the [style guide](/docs/contribute/style/style-guide/)?
{{% /capture %}}
{{% capture body %}}
## Types of contributor
- A _member_ of the Kubernetes organization has [signed the CLA](/contribute/start#sign-the-cla)
and contributed some time and effort to the project. See
[Community membership](
for specific criteria for membership.
- A SIG Docs _reviewer_ is a member of the Kubernetes organization who has
expressed interest in reviewing documentation pull requests and who has been
added to the appropriate Github group and `OWNERS` files in the Github
repository, by a SIG Docs Approver.
- A SIG Docs _approver_ is a member in good standing who has shown a continued
commitment to the project and is granted the ability to merge pull requests
and thus to publish content on behalf of the Kubernetes organization.
Approvers can also represent SIG Docs in the larger Kubernetes community.
Some of the duties of a SIG Docs approver, such as coordinating a release,
require a significant time commitment.
## Ways to contribute
This list is divided into things anyone can do, things Kubernetes organization
members can do, and things that require a higher level of access and familiarity
with SIG Docs processes. Contributing consistently over time can help you
understand some of the tooling and organizational decisions that have already
been made.
This is not an exhaustive list of ways you can contribute to the Kubernetes
documentation, but it should help you get started.
- [Anyone](/docs/contribute/start/)
- File actionable bugs
- [Member](/docs/contribute/start/)
- Improve existing docs
- Bring up ideas for improvement on Slack or SIG docs mailing list
- Improve docs accessibility
- Provide non-binding feedback on PRs
- Write a blog post or case study
- [Reviewer](/docs/contribute/intermediate/)
- Document new features
- Triage and categorize issues
- Review PRs
- Create diagrams, graphics assets, and embeddable screencasts / videos
- Localization
- Contribute to other repos as a docs representative
- Edit user-facing strings in code
- Improve code comments, Godoc
- [Approver](/docs/contribute/advanced/)
- Publish contributor content by approving and merging PRs
- Participate in a Kubernetes release team as a docs representative
- Propose improvements to the style guide
- Propose improvements to docs tests
- Propose improvements to the Kubernetes website or other tooling
{{% /capture %}}
@@ -0,0 +1,87 @@
title: Advanced contributing
slug: advanced
content_template: templates/concept
weight: 30
{{% capture overview %}}
This page assumes that you've read and mastered the
[Start contributing](/docs/contribute/start/) and
[Intermediate contributing](/docs/contribute/intermediate/) topics and are ready
to learn about more ways to contribute. You need to use the Git command line
client and other tools for some of these tasks.
{{% /capture %}}
{{% capture body %}}
## Be the PR Wrangler for a week
SIG Docs approvers are added to the
[PR Wrangler rotation scheduler](
for weekly rotations. The PR wrangler's duties include:
- Review incoming pull requests daily.
- Help new contributors sign the CLA, and close any PR where the CLA hasn't
been signed for two weeks. PR authors can reopen the PR after signing the
CLA, so this is a low-risk way to make sure nothing gets merged without a
signed CLA.
- Provide feedback on proposed changes, including helping facilitate technical
review from members of other SIGs.
- Merge PRs when they are ready, or close PRs that shouldn't be accepted.
- Triage and tag incoming issues daily. See
[Intermediate contributing](/docs/contribute/intermediate/) for guidelines
about how SIG Docs uses metadata.
## Propose improvements
After you've been contributing to the Kubernetes documentation for a while, you
may have ideas for improvement to the style guide, the toolchain used to build
the documentation, the website style, the processes for reviewing and merging
pull requests, or other aspects of the documentation. For maximum transparency,
these types of proposals need to be discussed in a SIG Docs meeting or on the
[kubernetes-sig-docs mailing list](!forum/kubernetes-sig-docs).
In addition, it can really help to have some context about the way things
currently work and why past decisions have been made before proposing sweeping
changes. The quickest way to get answers to questions about how the documentation
currently works is to ask in the `#sig-docs` Slack channel on
After discussion has taken place and the sig is in agreement about the desired
outcome, you can work on the proposed changes in the way that is the most
appropriate. For instance, an update to the style guide or the website's
functionality might involve opening a pull request, while a change related to
documentation testing might involve working with sig-testing.
## Coordinate docs for a Kubernetes release
Each Kubernetes release is coordinated by a team of people participating in the
sig-release special interest group (SIG). Others on the release team for a given
release include an overall release lead, as well as representatives from sig-pm,
sig-testing, and others. To find out more about Kubernetes release processes,
refer to
The SIG Docs representative for a given release coordinates the following tasks:
- Monitor the feature-tracking spreadsheet for new or changed features with an
impact on documentation. If documentation for a given feature won't be ready
for the release, the feature may not be allowed to go into the release.
- Attend sig-release meetings regularly and give updates on the status of the
docs for the release.
- Review and copyedit feature documentation drafted by the sig responsible for
implementing the feature.
- Merge release-related pull requests and maintain the Git feature branch for
the release.
- Mentor other SIG Docs contributors who want to learn how to do this role in
the future. This is known as "shadowing".
- Publish the documentation changes related to the release when the release
artifacts are published.
Coordinating a release is typically a 3-4 month commitment, and the duty is
rotated among SIG Docs approvers.
{{% /capture %}}
@@ -0,0 +1,9 @@
title: Reference docs overview
main_menu: true
weight: 80
Much of the Kubernetes reference documentation is generated from Kubernetes
source code, using scripts. The topics in this section document how to generate
this type of content.
Oops, something went wrong.

0 comments on commit 5ae0d0d

Please sign in to comment.