From a13814ba6e23904a54761675860935167a45153c Mon Sep 17 00:00:00 2001 From: RichardJJG Date: Mon, 19 Jul 2021 14:37:53 +0100 Subject: [PATCH] Added rest of K8s style guide, where applicable (#4031) * Added rest of K8s style guide, where applicable * Wording tweak --- docs/help/contributor/README.md | 5 ++-- .../style-guide/documenting-code.md | 24 ++++++++++--------- .../style-guide/style-and-formatting.md | 23 ++++++++++++++---- .../style-guide/voice-and-language.md | 19 +++++++++++---- .../style-guide/word-and-phrase-list.md | 4 ++++ 5 files changed, 53 insertions(+), 22 deletions(-) diff --git a/docs/help/contributor/README.md b/docs/help/contributor/README.md index 67d912092..1420a4eda 100644 --- a/docs/help/contributor/README.md +++ b/docs/help/contributor/README.md @@ -28,9 +28,8 @@ ### Style -!!! note "A note to first-time contributors" - You don't need to read the whole style guide before contributing to Knative documentation. - Unpolished contributions delivered early are better than perfect contributions delivered late. +You don't need to read the whole style guide before contributing to Knative documentation. +Unpolished contributions delivered early are better than perfect contributions delivered late. If you notice gaps in the style guide or have queries, please post in [the Docs Slack channel](https://knative.slack.com/archives/C9CV04DNJ). diff --git a/docs/help/contributor/style-guide/documenting-code.md b/docs/help/contributor/style-guide/documenting-code.md index c2fbad774..2aec68a57 100644 --- a/docs/help/contributor/style-guide/documenting-code.md +++ b/docs/help/contributor/style-guide/documenting-code.md @@ -4,6 +4,7 @@ //todo ## Words requiring code formatting + Apply code formatting only to special-purpose text: * Filenames @@ -69,10 +70,10 @@ Apply code formatting only to special-purpose text: >It meets these criteria: ->* Explicitly mentions running the command (this isn’t always obvious) -* **Uses “run”** (and not “type”, “execute”, etc -- we want consistency) -* Starts with the key information that describes the command, e.g. “To do X...run Y command:”, “Do X by running Y command:” -* As short as possible +>* It explicitly mentions running the command, which isn’t always obvious +* It uses “run”; not “type”, “execute”, etc -- we want consistency +* It describes what the command does before stating the command. +* It's as short as possible > If you must deviate from the standard line, ensure you still meet the above criteria. @@ -110,14 +111,15 @@ Apply code formatting only to special-purpose text: Where `` is the name of your Knative Service. ## Documenting YAML -//TODO CONTENT TABS (ex. kn + YAML) + + >When documenting YAML, use two steps. Use step 1 to create the YAML file, and step 2 to apply the YAML file. ->Use **kubectl apply** for files/objects that the user creates — it works for both “create” and “update”, and the source of truth is their local files. +>Use **kubectl apply** for files/objects that the user creates: it works for both “create” and “update”, and the source of truth is their local files. ->Use **kubectl edit** for files which are shipped as part of the Knative software, like the serving/eventing ConfigMaps. +>Use **kubectl edit** for files which are shipped as part of the Knative software, like the Knative Serving and Knative Eventing ConfigMaps. -> be sure to use ```yaml at the beginning of your code block if you are typing YAML code as part of a CLI command +> Write ```yaml at the beginning of your code block if you are typing YAML code as part of a CLI command. === ":white_check_mark: Correct" @@ -163,7 +165,7 @@ Apply code formatting only to special-purpose text: >Format variables in code blocks like so: -> - All lower case +> - All lowercase - Hyphens between words - Explanation for each variable below code block - Explanation format is “Where... `` is…" @@ -192,14 +194,14 @@ Apply code formatting only to special-purpose text: Where: * `` is the name of your Knative Service. - * `` is the desired name of your revision + * `` is the desired name of your revision. === ":no_entry: Incorrect" ```bash kn create service --revision-name ``` Where `` is the name of your Knative Service.
- Where `` is the desired name of your revision + Where `` is the desired name of your revision. diff --git a/docs/help/contributor/style-guide/style-and-formatting.md b/docs/help/contributor/style-guide/style-and-formatting.md index 76d2197a7..28d5374fa 100644 --- a/docs/help/contributor/style-guide/style-and-formatting.md +++ b/docs/help/contributor/style-guide/style-and-formatting.md @@ -1,6 +1,7 @@ -# Formatting standard and conventions +# Formatting standards and conventions ## Documenting Knative API Objects + > Use upper camel case for Knative API objects. |:white_check_mark: Correct |:no_entry: Incorrect @@ -10,6 +11,7 @@ |ContainerSource | Container Source ## Using parentheses + >Don’t use parentheses, unless it’s the first instance in a page to explain an acronym that isn’t immediately obvious. >Parenthetical statements especially should be avoided because if something is important enough to be in the sentence, it should be fully part of that sentence. @@ -19,11 +21,10 @@ |Install the Custom Resource Definition (CRD) | Check your CLI (you should see it there) |Knative Serving will create a Revision | Knative will create a Revision (a stateless, snapshot in time of your code and configuration) - ## Use sentence case for titles and headings -> Use sentence case for all titles and headings. Only capitalize the first -word of the heading, except for proper nouns or acronyms. +> Use sentence case for all titles and headings. Only capitalize the first word of the heading, +proper nouns, and acronyms. |:white_check_mark: Correct |:no_entry: Incorrect |--------------------|----- @@ -49,3 +50,17 @@ between the number and the unit. |3` `GB | 3 GB |4` `CPUs | 4 CPUs |14% | 14` `% + +## Use bold for user interface elements + +|:white_check_mark: Correct |:no_entry: Incorrect +|--------------------|----- +|Click **Fork** | Click "Fork" +|Select **Other** | Select "Other" + +## Use the international standard for punctuation inside quotes + +|:white_check_mark: Correct |:no_entry: Incorrect +|--------------------|----- +|Events are recorded with an associated "stage". | Events are recorded with an associated "stage." +|The copy is called a "fork". | The copy is called a "fork." diff --git a/docs/help/contributor/style-guide/voice-and-language.md b/docs/help/contributor/style-guide/voice-and-language.md index b99f5ffe7..192bc0c44 100644 --- a/docs/help/contributor/style-guide/voice-and-language.md +++ b/docs/help/contributor/style-guide/voice-and-language.md @@ -14,8 +14,8 @@ |The YAML file specifies the replica count. | The replica count is specified in the YAML file. ## Use simple and direct language -> Use simple and direct language. Avoid using unnecessary phrases, such as saying -"please." +> Use simple and direct language. Avoid using unnecessary words, such as +"please". |:white_check_mark: Correct |:no_entry: Incorrect |----------------------------|---- @@ -23,11 +23,11 @@ |See the configuration file. | Please see the configuration file. |View the Pods. | With this next command, we'll view the Pods. -## Address the reader as "you" (Avoid using "we") +## Address the reader as "you", not "we" |:white_check_mark: Correct |:no_entry: Incorrect |---------------------------------------|------ -|You can create a `Deployment` by ... | We'll create a `Deployment` by ... +|You can create a `Deployment` by ... | We can create a `Deployment` by ... |In the preceding output, you can see...| In the preceding output, we can see ... |This page teaches you how to use pods. | In this page, we are going to learn about pods. @@ -58,3 +58,14 @@ identifies the information accordingly. |------------------------------------|------ |In version 1.4, ... | In the current version, ... |The Federation feature provides ... | The new Federation feature provides ... + +## Avoid words that assume a specific level of understanding + +Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value. + +|:white_check_mark: Correct |:no_entry: Incorrect +|----------------------|------ +|Include one command in ... | Include just one command in ... +|Run the container ... | Simply run the container ... +|You can remove ... | You can easily remove ... +|These steps ... | These simple steps ... diff --git a/docs/help/contributor/style-guide/word-and-phrase-list.md b/docs/help/contributor/style-guide/word-and-phrase-list.md index 938b24cb5..9b7e156f1 100644 --- a/docs/help/contributor/style-guide/word-and-phrase-list.md +++ b/docs/help/contributor/style-guide/word-and-phrase-list.md @@ -10,13 +10,17 @@ For the correct spellings of words, see [Merriam-Webster](https://www.merriam-we | component | Component | | | ConfigMap | configmap
cm
config map
Config Map | | | CloudEvent | cloud event
Cloud Event | | +| Docker | docker | | | event | Event | | | event source | Event Source | | | hostname | host name | | | Knative Eventing | eventing
Eventing Component | | | Knative Service
Service | Knative service
service
ksvc
svc | | | Knative Serving | serving
Serving Component | | +| Kubernetes | kubernetes | | | minikube | Minikube | https://minikube.sigs.k8s.io/docs/start/ | +| on-premises | on-prem
on-premise | | +| SIG Docs | SIG-DOCS
Sig-docs
Sig-Docs
Sig Docs | | | standard input | stdin
STDIN | | | standard output | stdout
STDOUT | | | Trigger | trigger | |