kubernetes
/
community
mirror of https://github.com/kubernetes/community.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3125 from mrbobbytables/style-guide 

Documentation style guide
This commit is contained in:
Kubernetes Prow Robot 2019-01-30 20:46:52 -08:00 committed by GitHub
parent 362bc1c406 75752cc3b6
commit 74ff7245e8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 678 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

678
contributors/guide/style-guide.md Normal file
View File

@ -0,0 +1,678 @@
---
title: Documentation Style Guide
---
# Documentation Style Guide
This style guide is for content in the Kubernetes github [community repository].
It is an extension of the [Kubernetes documentation style-guide].
These are **guidelines**, not rules. Use your best judgement.
- [Cheatsheet](#cheatsheet)
- [Content design, formatting, and language](#content-formatting-and-language)
- [Contact information](#contact-information)
- [Dates and times](#dates-and-times)
- [Diagrams, images and other assets](#diagrams-images-and-other-assets)
- [Document Layout](#document-layout)
- [Formatting text](#formatting-text)
- [Language, grammar, and tone](#language-grammar-and-tone)
- [Moving a document](#moving-a-document)
- [Punctuation](#punctuation)
- [Quotation](#quotation)
- [Markdown formatting](#markdown-and-formatting)
- [Code Blocks](code-blocks)
- [Emphasis](#emphasis)
- [Headings](#headings)
- [Horizontal Lines](#horizontal-lines)
- [Line Length](#line-length)
- [Links](#links)
- [Lists](#lists)
- [Metadata](#metadata)
- [Tables](#tables)
- [Attribution](#attribution)
## Cheatsheet
### Cheatsheet: Content design, formatting, and language
**[Contact information:](#contact-information)**
- Use official Kubernetes contact information.
**[Dates and times:](#dates-and-times)**
- Format dates as `month day, year`. (December 13, 2018)
- When conveying a date in numerical form, use [ISO 8601] Format: `yyyy-mm-dd`.
- Use the 24 hour clock when referencing time.
- Times for single events (example: KubeCon) should be expressed in an absolute
time zone such as Pacific Standard Time (PST) or Coordinated Universal Time
(UTC).
- Times for reoccurring events should be expressed in a time zone that follows
Daylight Savings Time (DST) such as Pacific Time (PT) or Eastern Time (ET).
- Supply a link to a globally available time zone converter service.
- `http://www.thetimezoneconverter.com/?t=<TIME REFERENCE>&tz=<TZ REFERENCE>`
**[Diagrams, images and other assets:](#diagrams-images-and-other-assets)**
- Images and other assets should be stored in the same directory as the document
that is referencing it.
- Filenames should be lowercase and descriptive of what they are referencing.
- Avoid excessively large images or include a smaller one while linking to a
higher resolution version of the same image.
- Use the [Kubernetes icon set] for architectural diagrams.
**[Document Layout:](#document-layout)**
- Documents should follow the general template of:
- Document metadata (if appropriate).
- Title in `H1` (a single `#`).
- A brief description or summary of the document.
- A table of contents.
- The general body of document.
- Do not repeat content. Instead link back to the canonical source.
- Large content or topic shifts should be separated with a horizontal rule.
**[Formatting text:](#formatting-text)**
- API objects:
- Follow the established [API naming convention] when referring to API Objects.
- Do not split API object names into their components.
- Use `code` style for API objects or object parameters.
- Use **bold text** for user interface elements.
- Use _italics_ to emphasize a new topic or subject for the first time.
- Use angle brackets (`<` and `>`) to enclose a placeholder reference.
- Apply `code` styling to:
- Filenames, directories, and paths.
- Command line examples and flags.
- Object field names.
**[Language, grammar and tone:](#language)**
- Documentation should be written in English.
- Prefer an active voice and present tense when possible.
- Use simple and direct language.
- Use gender-neutral language.
- Avoid personal pronouns ("I," "we," "us," "our," and "ours").
- Address the reader as "you" instead of "we".
- Do not use Latin phrases.
- Avoid jargon and idioms.
- If using acronyms, ensure they are clearly defined in the same document.
- If using an abbreviation, spell it out the first time it is used in the
document unless it is commonly known. (example: TCP/IP)
**[Moving a document:](#moving-a-document)**
- Use `[git-mv]` to move documents.
- Commit moved documents separately from any other changes.
- When a document has moved, leave a tombstone file with a removal date in its
place.
**[Punctuation:](#punctuation)**
- Do not use punctuation in headings.
- End full sentences with a period.
- **Exception:** When a sentence ends with a URL or if the text would be
unclear if the period is a part of the previous object or word.
- Add a single space after a period when beginning a new sentence.
- Avoid usage of exclamation points unless they are a part of a code example.
- Use an [Oxford comma] when a list contains 3 or more elements.
**[Quotation:](#quotes)**
- Use double-quotation marks (`" "`) over single-quotation marks (`' '`).
- **Exception:** In code snippets where quotation marks have specific meaning.
- **Exception:** When nesting quotation marks inside another set of quotation
marks.
- Punctuation should be outside of quotation marks following the international
(British) standard.
### Cheatsheet: Markdown
**[Code blocks:](#code-blocks)**
- When possible, reference the language at the beginning of a Code Block.
- When a code block is used to reference a shell, do not include the command
prompt (`$`).
- **Exception:** When a code block is used to display raw shell output.
- Separate commands from output.
**[Emphasis:](#emphasis)**
- Use two asterisks (`**`) for **Bold** text.
- Use an underscore (`_`) for _Italics_.
- Use two tildes (`~~`) for ~~Strikethrough~~.
**[Headings:](#headings)**
- Use a single `H1` (`#`) Heading per document.
- **Exception:** `H1` may be used multiple times in the same document when
there is a large content shift or "chapter" change.
- Follow the Header hierarchy of `H2` > `H3` > `H4` > `H5` > `H6`.
- Use sentence-style capitalization in titles (first word and proper nouns).
- Avoid using special characters.
- Leave exactly 1 new line after a heading.
- Avoid using links in headings.
**[Horizontal rules:](#horizontal-lines)**
- Use three dashes (`---`) to denote a horizontal rule.
- Use a horizontal rule (`---`) to logically separate large sections.
**[Line length:](#line-length)**
- Prefer an 80 character line limit.
**[Links:](#links)**
- Prefer using reference style links over inline style links.
- When linking within the same directory, use a relative link.
- When linking to a document outside of the current directory, use the absolute
path from the root of the repository.
- When linking to a file in another Kubernetes github repository, use the
`k8s.io` url shortener.
- git.k8s.io -> github.com/kubernetes
- sigs.k8s.io -> github.com/kubernetes-sigs
**[Lists:](#lists)**
- Capitalize the first character of each entry unless the item is explicitly
case sensitive.
- End each entry with a period if it is a sentence or phrase.
- Use a colon (`:`) to separate a list item name from the explanatory text.
- Leave a blank line after each list.
- Use `-` for unordered lists.
- For ordered lists repeating `1.` may be used.
- When inserting a code block into an ordered list, indent (space) an additional
two times.
**[Metadata:](metadata)**
- If the document is intended to be surfaced on the Contributor Site; include a
yaml metadata header at the beginning of the document.
- Metadata must include the `title` attribute.
**[Tables:](#tables)**
- Use tables for structured information.
- Tables do not need to adhere to the suggested line length.
- Avoid long inline links.
- Do not use excessively wide tables.
---
## Content design, formatting, and language
### Contact information
- Use official Kubernetes contact information.
- Use official community contact email addresses. There should be no personal
or work contact information included in public documentation; instead use
addresses like the [SIG Google groups] or managed accounts such as
community@kubernetes.io.
- **Good example:** community@kubernetes.io
- **Bad example:** bob@example.com
### Dates and times
The Kubernetes Contributor Community spans many regions and time zones.
Following a consistent pattern and avoiding shorthand improves the readability
for every member.
- Format dates as `month day, year`. (December 13, 2018)
- **Good example:** October 24, 2018
- **Bad example:** 10/24/18
- When conveying a date in numerical form, use [ISO 8601] Format: `yyyy-mm-dd`.
- **Good example:** 2018-10-24
- **Bad example:** 10/24/18
- Use the 24 hour clock when referencing time.
- **Good example:** 15:30
- **Bad example:** 3:30pm
- Times for single events (example: KubeCon) should be expressed in an absolute
time zone such as Pacific Standard Time (PST) or Coordinated Universal Time
(UTC).
- **Good example:** The Seattle Contributor Summit starts at 9:00 PST
- **Bad example:** The Seattle Contributor Summit starts at 9:00 PT
- Times for reoccurring events should be expressed in a time zone that follows
Daylight Savings Time (DST) such as Pacific Time (PT) or Eastern Time (ET).
- Times that follow DST are used as they adjusts automatically. If UTC or
other non-DST compatible time zones were used, content would have to be
updated multiple times per year to adjust times.
- **Good example:** 13:30 PT
- **Bad example:** 16:30 EST
- Supply a link to a globally available time zone converter service.
- `http://www.thetimezoneconverter.com/?t=<TIME REFERENCE>&tz=<TZ REFERENCE>`
```
The weekly SIG meeting is at [13:30 PT].
[13:30 PT]: http://www.thetimezoneconverter.com/?t=13:30&tz=PT%20%28Pacific%20Time%29
```
### Diagrams, images and other assets
- Images and other assets should be stored in the same directory as the document
that is referencing it.
- Filenames should be lowercase and descriptive of what they are referencing.
- **Good example:** `deployment-workflow.jpg`
- **Bad example:** `image1.jpg`
- Avoid excessively large images or include a smaller one while linking to a
higher resolution version of the same image.
- Use the [Kubernetes icon set] for architectural diagrams.
### Document Layout
Adhering to a standard document layout ensures that each page can intuitively
be navigated once a reader is familiar with the standard layout.
- Documents should follow the general template of:
- Document metadata (if appropriate).
- Title in `H1` (a single `#`).
- A brief description or summary of the document.
- A table of contents.
- The general body of document.
- Do not repeat content. Instead link back to the canonical source.
- It is easy for content to become out of sync if it is maintained in
multiple places. Linking back to the canonical source ensures that the
documentation will be accurate and up to date.
- Large content or topic shifts should be separated with a horizontal rule.
### Formatting text
The formatting guidelines have been selected to mirror or augment the
[Kubernetes documentation style-guide]. Remaining consistent across the
different content sources improves the overall readability and understanding of
the documentation being presented in addition to giving the project a unified
external appearance.
- API objects:
- Follow the established [API naming convention] when referring to API Objects.
- Do not split API object names into their components.
- **Good example:** A `Pod` contains a `PodTemplateSpec`.
- **Bad example:** A `Pod` contains a `Pod Template Spec`.
- Use `code` style for API objects or object parameters.
- **Good example:** A `Deployment` contains a `DeploymentSpec`.
- **Bad example:** A Deployment contains a DeploymentSpec.
- Use angle brackets (`<` and `>`) to surround a placeholder references.
- **Good example:** `kubectl describe pod <pod-name>`
- **Bad example:** `kubectl describe pod pod-name`
- Use **bold text** for user interface elements.
- **Good example:** Select **Other**.
- **Bad example:** Select "Other".
- Use _italic text_ to emphasize a new subject for the first time.
- **Good example:** A _cluster_ is a set of nodes.
- **Bad example:** A "cluster" is a set of nodes.
- `Code` styling should be applied to:
- Filenames, directories, and paths.
- **Good example:** The default manifest path is `/etc/kubernetes/manifests`.
- **Bad example:** The default manifest path is /etc/kubernetes/manifests.
- Command line examples and flags.
- **Good example:** The flag `--advertise-address` is used to denote the
IP address on which to advertise the apiserver to members of the cluster.
- **Bad example:** The flag --advertise-address is used to denote the IP
address on which to advertise the apiserver to members of the cluster.
- Object field names.
- **Good example:** Set the `externalTrafficPolicy` to Local.
- **Bad example:** Set the externalTrafficPolicy to Local.
### Language, grammar and tone
- Documentation should be written in English.
- Prefer an active voice and present tense when possible.
- Active voice is when the subject of the sentence performs the action.
Whereas with passive voice the subject receives the action. Writing with an
active voice in mind easily conveys to the reader who or what is performing
the action.
- **Good example:** Updating the Deployment triggers a new ReplicaSet to be
created.
- **Bad example:** A ReplicaSet is created by updating the Deployment.
- Use simple and direct language.
- Avoid using unnecessary or extra language. Be straightforward and direct.
- **Good example:** Wait for the Pod to start.
- **Bad example:** Please be patient and wait for the Pod to start.
- Use gender-neutral language.
- Avoid gendered pronouns preferring the [singular "they"][singular-they]
unless referring to the person's by their preferred gender. For further
information on the subject, see [Microsoft's guide to bias-free communication]
and [Wikipedia's entry for the Singular they].
- **Good example:** chair or moderator
- **Bad example:** chairman
- Avoid personal pronouns ("I," "we," "us," "our," and "ours").
- In most cases personal pronouns should be avoided as they can lead to
confusion regarding who they are referring to.
- **Good example:** The release-team shepherded the successful release of 1.13.
- **Bad example:** We shepherded the successful release of 1.13.
- Address the reader as "you" instead of "we".
- Addressing the reader directly using "you" clearly denotes the target.
There is no confusion as there would be with "we" or "us".
- **Good example:** You will create a new cluster with kubeadm.
- **Bad example:** We will create a new cluster with kubeadm.
- Do not use Latin phrases.
- [Latin phrases] can make it difficult for readers not familiar with them to
grasp their meaning.
- Some useful alternatives include:
| Latin Phrase | Alternative |
|:------------:|:-----------:|
| e.g. | for example |
| et al. | and others |
| i.e. | that is |
| via | using |
- **Good example:** For example Deployments, ReplicaSets...
- **Bad example:** e.g. Deployments, ReplicaSets...
- Avoid jargons and idioms.
- Jargon and idioms tend to rely on regional or tribal knowledge. They make
it difficult to understand for both newcomers and those whose native
language is something other than English. They should be avoided when
possible.
- **Good example:** Internally, the kube-apiserver...
- **Bad example:** Under the hood the kube-apiserver...
- **Good example:** We will start the project in early 2019.
- **Bad example:** We will kick off the initiative in 2019.
- If using an abbreviation, spell it out the first time it is used in the
document unless it is commonly known. (example: TCP/IP)
- Abbreviations in this context applies to abbreviations, acronyms and
initialisms.
- **Good example:** A _CustomResourceDefinition_ (CRD) extends the Kubernetes
API.
- **Bad example:** A CRD extends the Kubernetes API.
### Moving a Document
- Use `[git-mv]` to move documents.
- `git-mv` will safely move/rename a file, directory, or symlink and
automatically update the git index.
- **Good example:** `git mv /old/mydoc.md /new/mydoc.md`
- **Bad example:** `mv /old/mydoc.md /new/mydoc.md`
- Commit moved documents separately from any other changes.
- A separate commit clearly preserves the history of the relocated documents
and makes it easier to review.
- When a document has moved, leave a tombstone file with a removal date in its
place.
- Tombstones function as a pointer and give users a time to update their own
documentation and bookmarks. Their usefulness is time-bounded and should be
removed when they would logically no longer serve their purpose.
```markdown
This file has moved to https://git.k8s.io/community/contributors/guide/README.md.
This file is a placeholder to preserve links. Please remove after 2019-03-10 or the release of kubernetes 1.10, whichever comes first.
```
### Punctuation
- Do not use punctuation in headings.
- End full sentences with a period.
- **Exception:** When a sentence ends with a URL or if the text would be
unclear if the period is a part of the previous object or word.
- Add a single space after a period when beginning a new sentence.
- Avoid usage of exclamation points unless they are a part of a code example.
- Use an [Oxford comma] when a list contains 3 or more elements.
- **Good example:** Deployments, ReplicaSets, and DaemonSets.
- **Bad example:** Deployments, ReplicaSets and DaemonSets.
### Quotation
- Use double-quotation marks (`" "`) over single-quotation marks (`' '`).
- **Exception:** In code snippets where quotation marks have specific meaning.
- **Exception:** When nesting quotation marks inside another set of quotation
marks.
- Punctuation should be outside of quotation marks following the international
(British) standard.
---
## Markdown formatting
### Code blocks
- When possible, reference the language at the beginning of a Code Block.
- The two markdown renderers used by the Kubernetes community
([GitHub][gh-code-hl-list] and [Hugo][hugo-code-hl-list]) support code
highlighting. This can be enabled by supplying the name of the language
after the three back-ticks (`` ``` ``) at the start of a code block.
- **Good example:**
`````
```go
import (
"fmt"
...
)
```
`````
- **Bad example:**
`````
```
import (
"fmt"
...
)
```
`````
- When a code block is used to reference a shell, do not include the command
prompt (`$`)
- When a code block is referencing a shell, it is implied that it is a
command prompt. The exception to this is when a code block is being used
for raw shell output such as debug logs.
- **Good example:**
```
kubectl get pods -o wide
```
- **Bad example:**
```
$ kubectl get pods -o wide
```
- Separate commands from output.
- Separating the command from the output makes both the command and output
more generally readable.
- **Good example:**
```
kubectl get pods
```
```
NAME READY STATUS RESTARTS AGE IP NODE
nginx 1/1 Running 0 13s 10.200.0.4 worker0
```
- **Bad example:**
```
kubectl get pods
NAME READY STATUS RESTARTS AGE IP NODE
nginx 1/1 Running 0 13s 10.200.0.4 worker0
```
### Emphasis
Markdown has multiple ways of indicating each type of emphasis. Adhering to a
standard across documentation improves supportability.
- Use two asterisks (`**`) for **Bold** text.
- **Good example:** `This is **bold** text.`
- **Bad example:** `This should not be used for __bold__.`
- Use an underscore (`_`) for _Italics_.
- **Good example:** This is _italics_.`
- **Bad example:** This should not be used for *italics*.`
- Use two tildes (`~~`) for ~~Strikethrough~~.
- **Good example:** `This is ~~strikethrough~~`
- **Bad example:** `This should not be used for ~strikethrough~.`
### Headings
Adhering to a standard across documentation improves both readability and
overall supportability across multiple documents.
- Use a single `H1` (`#`) Heading per document.
- **Exception:** `H1` may be used multiple times in the same document when
there is a large content shift or "chapter" change.
- Follow the Header hierarchy of `H2` > `H3` > `H4` > `H5` > `H6`.
- Use sentence-style capitalization in titles (first word and proper nouns).
- Avoid using special characters.
- Leave exactly 1 new line after a heading.
- Avoid using links in headings.
### Horizontal rules
Markdown has multiple ways of indicating a horizontal rule. Adhering to a
standard across documentation improves supportability.
- Use three dashes (`---`) to denote a horizontal rule.
- **Good example:** `---`
- **Bad example:** `===`
- Use a horizontal rule (`---`) to logically separate large sections.
### Line length
- Prefer an 80 character line limit.
- There is no specific general best practice for Markdown line length. The
commonly used 80 character guideline is preferable for general text review
and editing.
### Links
Markdown provides two primary methods to link to content: inline links and
relative links. However, how and what they're being linked to can vary widely.
- Prefer using reference style links over inline style links.
- Reference links are shorter and easier to read. They have the added benefit
of being reusable throughout the entire document.
- The link itself should be at the bottom of the document. If the document is
large or covers many topics, place the link at the end of the logical
chapter or section.
- **Example:**
```
See the [Code of Conduct] for more information.
[code of conduct]: https://git.k8s.io/community/code-of-conduct.md
```
- **Example:**
```
See the [Code of Conduct][coc] for more information.
[coc]: https://git.k8s.io/community/code-of-conduct.md
```
- When linking within the same directory, use a relative link.
- Links to files within the same directory are short and readable already.
They do not warrant expanding the full path.
- When the file is referenced multiple times within the same document,
consider using a reference link for a quicker shorthand reference.
- **Example:**
```
See the [Code of Conduct](code-of-conduct.md) for more information
```
- **Example:**
```
See the [Code of Conduct][coc] for more information
[coc]: code-of-conduct.md
```
- When linking to a document outside of the current directory, use the absolute
path from the root of the repository.
- Using the absolute path ensures that if the source document is relocated,
the link to the target or destination document will remain intact and not
have to be updated.
- **Example:**
```
See the [Coding Convention] doc for more information.
[Coding Convention]: /contributors/guide/coding-conventions.md
```
- When linking to a file in another Kubernetes github repository, use the
`k8s.io` url shortener.
- The shorthand version will auto-expand linking to documents within the
master branch and can be used for multiple purposes.
| Short URL | Expanded URL |
|:-------------------:|:----------------------------------:|
| https://git.k8s.io | https://github.com/kubernetes |
| https://sigs.k8s.io | https://github.com/kubernetes-sigs |
- **Example:**
```
The super cool [prow tool] resides in the test-infra repo under the kubernetes organization
[prow tool]: https://git.k8s.io/test-infra/prow/README.md
```
### Lists
Adhering to a standard across documentation improves both readability and
overall supportability across multiple documents.
- Capitalize the first character of each entry unless the item is explicitly
case sensitive.
- End each entry with a period if it is a sentence or phrase.
- Use a colon (`:`) to separate a list item name from the explanatory text.
- Leave a blank line after each list.
- Use `-` for unordered lists.
- For ordered lists a repeating `1.` may be used.
- When inserting a code block into an ordered list, indent (space) an additional
two times.
### Metadata
- If the document is intended to be surfaced on the Contributor Site; include a
yaml metadata header at the beginning of the document.
- If the document is to be added to the Contributor Site, adding metadata
at the beginning of the document will improve the overall presentation of
the information. This metadata is similar to the metadata used in the
KEP process and is often referred to as _Frontmatter_ in common static
site generators such as [Jekyll] and [Hugo].
- The metadata header is a yaml block between two sets of `---`.
- **Example:**
```
---
title: Super Awesome Doc
---
```
- Metadata must include the `title` attribute.
- `title` will be used as the title of the document when rendered with
[Hugo].
### Tables
- Use tables for structured information.
- **Example:**
```
| Column 1 | Column 2 | Column 3 |
|:--------------:|:--------------:|:--------------:|
| test 1 | test 2 | test 3 |
| another test 1 | another test 2 | another test 3 |
```
- Tables do not need to adhere to the suggested line length.
- Markdown tables have an inherently longer line length, and cannot be
line wrapped.
- Avoid long inline links.
- Long inline links can make it difficult to work with markdown tables.
Prefer to use reference style links instead.
- Do not use excessively wide tables.
- Large wide tables do not render well. Try to break the information down
into something more easily presentable.
## Attribution
This style guide is heavily influenced by the great work from the content
management teams from [SIG-Docs], [Gitlab], [Google], and [Microsoft]. Without
their previous efforts this guide would not be nearly as concise as it should.
[community repository]: https://git.k8s.io/community
[Kubernetes documentation style-guide]: https://kubernetes.io/docs/contribute/style/style-guide/
[SIG Google groups]: /sig-list.md
[ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
[kubernetes icon set]: /icons
[API naming convention]: /contributors/devel/api-conventions.md#naming-conventions
[singular-they]: https://en.wikipedia.org/wiki/Singular_they
[Microsoft's guide to bias-free communication]: https://docs.microsoft.com/en-us/style-guide/bias-free-communication
[Wikipedia's entry for the Singular they]: https://en.wikipedia.org/wiki/Singular_they
[Latin phrases]: https://en.wikipedia.org/wiki/List_of_Latin_abbreviations
[Oxford comma]: https://www.grammarly.com/blog/what-is-the-oxford-comma-and-why-do-people-care-so-much-about-it/
[gh-code-hl-list]: https://github.com/github/linguist/blob/master/lib/linguist/languages.yml
[hugo-code-hl-list]: http://www.rubycoloredglasses.com/2013/04/languages-supported-by-github-flavored-markdown/
[git-mv]: https://git-scm.com/docs/git-mv
[jekyll]: https://jekyllrb.com/
[hugo]: https://gohugo.io/
[gitlab]: https://docs.gitlab.com/ee/development/documentation/styleguide.html
[google]: https://developers.google.com/style/
[microsoft]: https://docs.microsoft.com/en-us/style-guide/welcome/
[sig-docs]: https://kubernetes.io/docs/contribute/style/style-guide/