Use the following style guide for all writing assignments.
Use simple English in Spectro Cloud material unless explicitly stated otherwise in this guide. More importantly, simple language helps the reader retain information and more readily understand concepts.
| Good | Bad | |||
|---|---|---|---|---|
| The core Kubernetes API is flexible and can also be extended to support custom resources | The interior Kubernetes API is malleable and provides the capability for consumers to extended custom logic and inject custom logical resources | |||
| Drain the node before a version upgrade. | It is essential to drain the node prior to a version upgrade. |
|
Users read documentation to perform tasks or gather information. For users, these activities take place in their present, so the present tense is proper in most cases. Additionally, the present tense is simpler to read than the past or future tense.
Use the active voice whenever possible. The active voice is usually more direct and vigorous than the passive. When you write a sentence in the active voice, it is also usually shorter than in the passive voice.
Address the user when creating text content, use the noun, you. Use, we, when providing the user with recommendations. We want to take ownership of the guidance we provide, so avoid hiding using “it is recommended.”
| Good | Bad | |||
|---|---|---|---|---|
| You will be prompted to accept or reject the changes. | One will have the opportunity to accept or reject the changes. | |||
| Use the kubectl cli to create a namespace titled “mgmt” | The Kubectl CLI can be used to create namespaces titled “mgmt” | |||
| Prior to upgrading, ensure you have carefully reviewed the release notes for deprecation notices. | Release notes should be carefully verified for deprecation notices prior to an upgrade. | |||
Don't use ableist language. This avoids biases and harm when discussing disability and accessibility. Ableist language includes words or phrases such as crazy, insane, blind to or blind eye to, cripple, dumb, and others. This also includes action verbs with physical traits, such as jump and run. Choose alternative words depending on the context.
| Good | Bad | |||
|---|---|---|---|---|
| Navigate to the tab titled, Settings. | Jump to the next tab. | |||
| Before launch, give everything a final check for completeness and clarity. | Before launch, give everything a final sanity-check. |
|
Although some acronyms are widely understood and preferred to the spelled-out term, others are not well known or are familiar only to a specific group of customers. Define the acronym first.
Use gender-neutral pronouns. Avoid the following nouns he, him, his, she, or her as gender-neutral pronouns. The same applies to he/she or (s)he or other such punctuational approaches. Use the singular they.
Use title case for headings. If the heading is conceptual or non-task based, then start with a noun. Avoid using a noun that starts with an -ing.
| Good | Bad | |||
|---|---|---|---|---|
| Access Audit Logs | Access audit logs | |||
| Deploy the Infrastructure | Deploying the Infrastructure |
|
Show the command output to help the reader follow along and validate they are receiving the expected output.
$ kind create cluster
Creating cluster "kind" ...
✓ Ensuring node image (kindest/node:v1.25.3) 🖼
✓ Preparing nodes 📦
✓ Writing configuration 📜
✓ Starting control-plane 🕹️
✓ Installing CNI 🔌
✓ Installing StorageClass 💾
Set kubectl context to "kind-kind"
You can now use your cluster with:
kubectl cluster-info --context kind-kind
Have a nice day! 👋