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

Added rule and tidied up a bit (#4035) 

* Added rule and tidied up a bit

* Update docs/help/contributor/style-guide/style-and-formatting.md

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>

Co-authored-by: Ashleigh Brennan <abrennan@redhat.com>
This commit is contained in:
RichardJJG 2021-07-21 15:56:39 +01:00 committed by GitHub
parent b32d0901a5
commit 8b519d3f4a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 50 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,44 +1,46 @@
# Formatting standards and conventions
## Documenting Knative API Objects
## Titles and headings
> Use upper camel case for Knative API objects.
### Use sentence case for titles and headings
> Only capitalize proper nouns, acronyms, and the first word of the heading.
|:white_check_mark: Correct |:no_entry: Incorrect
|--------------------|-----
|Channels | channels
|Broker | broker
|ContainerSource | Container Source
|## Configure the feature | ## Configure the Feature
|### Using feature | ### Using Feature
|### Using HTTPS | ### Using https
## 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.
### Do not use code formatting inside headings
|:white_check_mark: Correct |:no_entry: Incorrect
|--------------------|-----
|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)
|## Configure the class annotation | ## Configure the \`class\` annotation
## Use sentence case for titles and headings
### Use imperatives for headings of procedures
> Use sentence case for all titles and headings. Only capitalize the first word of the heading,
proper nouns, and acronyms.
> For consistency, brevity, and to better signpost where action is expected of the reader, make procedure headings imperatives.
|:white_check_mark: Correct |:no_entry: Incorrect
|--------------------|-----
|Configuring feature | Configuring Feature
|Using feature | Using Feature
|Using HTTPS | Using https
|----------------------|-----
|## Install Knative Serving | ## Installation of Knative Serving
|### Configure DNS | ### Configuring DNS
|## Verify the installation | ## How to verify the installation
## Create descriptive links
## Links
### Make links descriptive
|:white_check_mark: Correct |:no_entry: Incorrect
|---------------------------------------|------
|Check out [this excellent article](https://medium.com/@heyoka/Correctnt-use-click-here-f32f445d1021) explaining <br> what makes a good hyperlink | Check out the article [here](https://medium.com/@heyoka/Correctnt-use-click-here-f32f445d1021)
|For an explanation of what makes a good hyperlink, see this [this article](https://medium.com/@heyoka/Correctnt-use-click-here-f32f445d1021).| See this article [here](https://medium.com/@heyoka/Correctnt-use-click-here-f32f445d1021).
## Use spaces in units of measurement
<!-- Add rule here, see https://github.com/knative/docs/issues/4034 -->
## Formatting
### Use nonbreaking spaces in units of measurement other than percent
> For most units of measurement, when you specify a number with the unit, use a nonbreaking space
between the number and the unit.
@ -51,14 +53,36 @@ between the number and the unit.
|4`&nbsp`CPUs | 4 CPUs
|14% | 14`&nbsp`%
## Use bold for user interface elements
### 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
## General style
### Use upper camel case for Knative API objects
|:white_check_mark: Correct |:no_entry: Incorrect
|--------------------|-----
|Channels | channels
|Broker | broker
|ContainerSource | Container Source
### Only use parentheses for acronym explanations
>Put an acronym inside parentheses after its explanation. Don’t use parentheses for anything else.
>Parenthetical statements especially should be avoided because readers skip them.
If something is important enough to be in the sentence, it should be fully part of that sentence.
|:white_check_mark: Correct |:no_entry: Incorrect
|--------------------|-----
|Custom Resource Definition (CRD) |Check your CLI (you should see it there)
|Knative Serving creates a Revision |Knative creates a Revision (a stateless, snapshot in time of your code and configuration)|
### Use the international standard for punctuation inside quotes
|:white_check_mark: Correct |:no_entry: Incorrect
|--------------------|-----

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

@ -1,4 +1,4 @@
## Voice and language
# Voice and language
## Use present tense
@ -50,7 +50,7 @@ Avoid making promises or giving hints about the future. If you need to talk
about a feature in development, add a boilerplate under the front matter that
identifies the information accordingly.
### Avoid statements that will soon be out of date
## Avoid statements that will soon be out of date
> Avoid using wording that becomes outdated quickly like "currently" and
"new". A feature that is new today is not new for long.