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

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 2021-07-19 14:37:53 +01:00 committed by GitHub
parent 5469d8e5cf
commit a13814ba6e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 53 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/help/contributor/README.md
View File

@ -28,9 +28,8 @@
### Style ### Style
!!! note "A note to first-time contributors" You don't need to read the whole style guide before contributing to Knative documentation.
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.
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). If you notice gaps in the style guide or have queries, please post in [the Docs Slack channel](https://knative.slack.com/archives/C9CV04DNJ).

24
docs/help/contributor/style-guide/documenting-code.md
View File

@ -4,6 +4,7 @@
//todo //todo
## Words requiring code formatting ## Words requiring code formatting
Apply code formatting only to special-purpose text: Apply code formatting only to special-purpose text:
* Filenames * Filenames
@ -69,10 +70,10 @@ Apply code formatting only to special-purpose text:
>It meets these criteria: >It meets these criteria:
>* Explicitly mentions running the command (this isn’t always obvious) >* It explicitly mentions running the command, which isn’t always obvious
* **Uses “run”** (and not “type”, “execute”, etc -- we want consistency) * It uses “run”; 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:” * It describes what the command does before stating the command.
* As short as possible * It's as short as possible
> If you must deviate from the standard line, ensure you still meet the above criteria. > 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. Where `<service-name>` is the name of your Knative Service.
## Documenting YAML ## 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. >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" === ":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> >Format variables in code blocks like so: <service-name>
> - All lower case > - All lowercase
- Hyphens between words - Hyphens between words
- Explanation for each variable below code block - Explanation for each variable below code block
- Explanation format is “Where... `<service-name>` is…" - Explanation format is “Where... `<service-name>` is…"
@ -192,14 +194,14 @@ Apply code formatting only to special-purpose text:
Where: Where:
* `<service-name>` is the name of your Knative Service. * `<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" === ":no_entry: Incorrect"
```bash ```bash
kn create service <service-name> --revision-name <revision-name> kn create service <service-name> --revision-name <revision-name>
``` ```
Where `<service-name>` is the name of your Knative Service.<br> 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.

23
docs/help/contributor/style-guide/style-and-formatting.md
View File

@ -1,6 +1,7 @@
# Formatting standard and conventions # Formatting standards and conventions
## Documenting Knative API Objects ## Documenting Knative API Objects
> Use upper camel case for Knative API objects. > Use upper camel case for Knative API objects.
|:white_check_mark: Correct |:no_entry: Incorrect |:white_check_mark: Correct |:no_entry: Incorrect
@ -10,6 +11,7 @@
|ContainerSource | Container Source |ContainerSource | Container Source
## Using parentheses ## Using parentheses
>Don’t use parentheses, unless it’s the first instance in a page to explain an acronym that isn’t immediately obvious. >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. >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) |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) |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 titles and headings
> Use sentence case for all titles and headings. Only capitalize the first > Use sentence case for all titles and headings. Only capitalize the first word of the heading,
word of the heading, except for proper nouns or acronyms. proper nouns, and acronyms.
|:white_check_mark: Correct |:no_entry: Incorrect |:white_check_mark: Correct |:no_entry: Incorrect
|--------------------|----- |--------------------|-----
@ -49,3 +50,17 @@ between the number and the unit.
|3`&nbsp`GB | 3 GB |3`&nbsp`GB | 3 GB
|4`&nbsp`CPUs | 4 CPUs |4`&nbsp`CPUs | 4 CPUs
|14% | 14`&nbsp`% |14% | 14`&nbsp`%
## 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."

19
docs/help/contributor/style-guide/voice-and-language.md
View File

@ -14,8 +14,8 @@
|The YAML file specifies the replica count. | The replica count is specified in the YAML file. |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
> Use simple and direct language. Avoid using unnecessary phrases, such as saying > Use simple and direct language. Avoid using unnecessary words, such as
"please." "please".
|:white_check_mark: Correct |:no_entry: Incorrect |:white_check_mark: Correct |:no_entry: Incorrect
|----------------------------|---- |----------------------------|----
@ -23,11 +23,11 @@
|See the configuration file. | Please see the configuration file. |See the configuration file. | Please see the configuration file.
|View the Pods. | With this next command, we'll view the Pods. |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 |: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 ... |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. |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, ... |In version 1.4, ... | In the current version, ...
|The Federation feature provides ... | The new Federation feature provides ... |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 ...

4
docs/help/contributor/style-guide/word-and-phrase-list.md
View File

@ -10,13 +10,17 @@ For the correct spellings of words, see [Merriam-Webster](https://www.merriam-we
| component | Component | | | component | Component | |
| ConfigMap | configmap<br>cm<br>config&nbsp;map<br>Config&nbsp;Map | | | ConfigMap | configmap<br>cm<br>config&nbsp;map<br>Config&nbsp;Map | |
| CloudEvent | cloud&nbsp;event<br>Cloud&nbsp;Event | | | CloudEvent | cloud&nbsp;event<br>Cloud&nbsp;Event | |
| Docker | docker | |
| event | Event | | | event | Event | |
| event&nbsp;source | Event&nbsp;Source | | | event&nbsp;source | Event&nbsp;Source | |
| hostname | host&nbsp;name | | | hostname | host&nbsp;name | |
| Knative&nbsp;Eventing | eventing<br>Eventing&nbsp;Component | | | Knative&nbsp;Eventing | eventing<br>Eventing&nbsp;Component | |
| Knative&nbsp;Service<br>Service | Knative&nbsp;service<br>service<br>ksvc<br>svc | | | Knative&nbsp;Service<br>Service | Knative&nbsp;service<br>service<br>ksvc<br>svc | |
| Knative&nbsp;Serving | serving<br>Serving&nbsp;Component | | | Knative&nbsp;Serving | serving<br>Serving&nbsp;Component | |
| Kubernetes | kubernetes | |
| minikube | Minikube | https://minikube.sigs.k8s.io/docs/start/ | | 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&nbsp;Docs | |
| standard&nbsp;input | stdin<br>STDIN | | | standard&nbsp;input | stdin<br>STDIN | |
| standard&nbsp;output | stdout<br>STDOUT | | | standard&nbsp;output | stdout<br>STDOUT | |
| Trigger | trigger | | | Trigger | trigger | |