Documenting Code¶

Looking for a template?

//todo

Words requiring code formatting¶

Apply code formatting only to special-purpose text:

Filenames
Path names
Any text that goes into a CLI

Specify the programming language¶

Specify the language your code is in as part of the code block

Specify non-language specific code, like CLI commands, with ```bash (see below for formatting).

Correct

package main

import "fmt"

func main() {
    fmt.Println("hello world")
}

Incorrect

package main

import "fmt"

func main() {
    fmt.Println("hello world")
}

Correct Formatting

```go
package main

import "fmt"

func main() {
    fmt.Println("hello world")
}
```

Incorrect Formatting

```bash
package main

import "fmt"

func main() {
    fmt.Println("hello world")
}
```

Documenting commands¶

The standard line is “X the Y by running the command:”

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

If you must deviate from the standard line, ensure you still meet the above criteria.

Correct

Create the service by running the command:

kn create service <service-name>

Where <service-name> is the name of your Knative Service.

Incorrect

Example 1:

Create the service:

kn create service <service-name>

Where <service-name> is the name of your Knative Service.

Example 2:

Run:

kn create service <service-name>

Where <service-name> is the name of your Knative Service.

Example 3:

Run the command below to create a service:

kn create service <service-name>

Where <service-name> 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 edit for files which are shipped as part of the Knative software, like the serving/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

Correct

Creating or updating a resource:
1. Create a YAML file using the template below:
```
# YAML FILE CONTENTS
```
2. Apply the YAML file by running the command:
```
kubectl apply --filename <filename>.yaml
```
  Where <filename> is the name of the file you created in the previous step.

Editing a ConfigMap:

kubectl -n <namespace> edit configmap <resource-name>

Incorrect

Example 1:

cat <<EOF | kubectl create -f -
# code
EOF

Example 2:

kubectl apply -f - <<EOF
# code
EOF

Referencing variables in code blocks¶

Format variables in code blocks like so:

All lower case

Hyphens between words

Explanation for each variable below code block

Explanation format is “Where... <service-name> is…"

If there are multiple variables, see below.

Single variable¶

Correct

kn create service <service-name>

Where <service-name> is the name of your Knative Service.

Incorrect

kn create service {SERVICE_NAME}

{SERVICE_NAME} = The name of your service

Multiple variables¶

Correct

kn create service <service-name> --revision-name <revision-name>

Where:

<service-name> is the name of your Knative Service.
<revision-name> is the desired name of your revision

Incorrect

kn create service <service-name> --revision-name <revision-name>

Where <service-name> is the name of your Knative Service.
Where <revision-name> is the desired name of your revision

CLI output¶

CLI Output should include the custom css "{ .bash .no-copy }" in place of "bash" which removes the "Copy to clipboard button" on the right side of the code block

Correct

<some-code>

Incorrect

<some-code>

Correct Formatting

```{ .bash .no-copy }
<some-code>
```

Incorrect Formatting

```bash
<some-code>
```