style-and-formatting.md

Formatting standards and conventions

Titles and headings

Use sentence case for titles and headings

Only capitalize proper nouns, acronyms, and the first word of the heading.

✅ Correct	⛔ Incorrect
## Configure the feature	## Configure the Feature
### Using feature	### Using Feature
### Using HTTPS	### Using https

Do not use code formatting inside headings

✅ Correct	⛔ Incorrect
## Configure the class annotation	## Configure the `class` annotation

Use imperatives for headings of procedures

For consistency, brevity, and to better signpost where action is expected of the reader, make procedure headings imperatives.

✅ Correct	⛔ Incorrect
## Install Knative Serving	## Installation of Knative Serving
### Configure DNS	### Configuring DNS
## Verify the installation	## How to verify the installation

Links

Describe what the link targets

✅ Correct	⛔ Incorrect
For an explanation of what makes a good hyperlink, see this this article.	See this article here.

Write links in Markdown, not HTML

✅ Correct	⛔ Incorrect
[Kafka Broker](../kafka-broker/README.md)	<a href="../kafka-broker/README.md">Kafka Broker</a>
[Kafka Broker](../kafka-broker/README.md){target=_blank}	<a href="../kafka-broker/README.md" target="_blank">Kafka Broker</a>

Include the .md extension in internal links

✅ Correct	⛔ Incorrect
[Setting up a custom domain](../serving/using-a-custom-domain.md)	[Setting up a custom domain](../serving/using-a-custom-domain)

Link to files, not folders

✅ Correct	⛔ Incorrect
[Kafka Broker](../kafka-broker/README.md)	[Kafka Broker](../kafka-broker/)

Ensure the letter case is correct

✅ Correct	⛔ Incorrect
[Kafka Broker](../kafka-broker/README.md)	[Kafka Broker](../kafka-broker/readme.md)

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.

Don't use spacing when the unit of measurement is percent.

✅ Correct	⛔ Incorrect
3&nbspGB	3 GB
4&nbspCPUs	4 CPUs
14%	14&nbsp%

Use bold for user interface elements

✅ Correct	⛔ Incorrect
Click Fork	Click "Fork"
Select Other	Select "Other"

Use tables for definition lists

When listing terms and their definitions, use table formatting instead of definition list formatting.

✅ Correct

| Value  | Description           |
|--------|-----------------------|
| Value1 | Description of Value1 |
| Value2 | Description of Value2 |

⛔ Incorrect

**Value1:**
Description of Value1

**Value2:**
Description of Value2

General style

Use upper camel case for Knative API objects

✅ Correct	⛔ 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.

✅ Correct	⛔ 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

✅ Correct	⛔ 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."