mirror of https://github.com/knative/docs.git
Added rest of K8s style guide, where applicable (#4031)
* Added rest of K8s style guide, where applicable * Wording tweak
This commit is contained in:
RichardJJG
GitHub
parent
5469d8e5cf
commit
a13814ba6e
|
|
@ -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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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 `<service-name>` is the name of your Knative Service.
|
||||
|
||||
## Documenting YAML
|
||||
//TODO CONTENT TABS (ex. kn + 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: <service-name>
|
||||
|
||||
> - All lower case
|
||||
> - All lowercase
|
||||
- Hyphens between words
|
||||
- Explanation for each variable below code block
|
||||
- Explanation format is “Where... `<service-name>` is…"
|
||||
|
|
@ -192,14 +194,14 @@ Apply code formatting only to special-purpose text:
|
|||
Where:
|
||||
|
||||
* `<service-name>` is the name of your Knative Service.
|
||||
* `<revision-name>` is the desired name of your revision
|
||||
* `<revision-name>` is the desired name of your revision.
|
||||
|
||||
=== ":no_entry: Incorrect"
|
||||
```bash
|
||||
kn create service <service-name> --revision-name <revision-name>
|
||||
```
|
||||
Where `<service-name>` is the name of your Knative Service.<br>
|
||||
Where `<revision-name>` is the desired name of your revision
|
||||
Where `<revision-name>` is the desired name of your revision.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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."
|
||||
|
|
|
|||
|
|
@ -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 ...
|
||||
|
|
|
|||
|
|
@ -10,13 +10,17 @@ For the correct spellings of words, see [Merriam-Webster](https://www.merriam-we
|
|||
| component | Component | |
|
||||
| ConfigMap | configmap<br>cm<br>config map<br>Config Map | |
|
||||
| CloudEvent | cloud event<br>Cloud Event | |
|
||||
| Docker | docker | |
|
||||
| event | Event | |
|
||||
| event source | Event Source | |
|
||||
| hostname | host name | |
|
||||
| Knative Eventing | eventing<br>Eventing Component | |
|
||||
| Knative Service<br>Service | Knative service<br>service<br>ksvc<br>svc | |
|
||||
| Knative Serving | serving<br>Serving Component | |
|
||||
| Kubernetes | kubernetes | |
|
||||
| minikube | Minikube | https://minikube.sigs.k8s.io/docs/start/ |
|
||||
| on-premises | on-prem<br>on-premise | |
|
||||
| SIG Docs | SIG-DOCS<br>Sig-docs<br>Sig-Docs<br>Sig Docs | |
|
||||
| standard input | stdin<br>STDIN | |
|
||||
| standard output | stdout<br>STDOUT | |
|
||||
| Trigger | trigger | |
|
||||
|
|
|
|||
Loading…
Reference in New Issue