Crossplane logo
Crossplane logo

Writing Style Guide

On this page

The most important points of the style guide include:

  • Avoid passive voice.
    • Active voice writing is stronger and direct. Active voice simplifies doc translations.
  • Use sentence-case headings.
    • Sentence case creates more casual and approachable writing.
  • Wrap lines at 80 characters.
    • Line wrapping improves review feedback.
  • Use present tense and avoid “will.”
    • Docs cover actions happening now and the results in real time.
  • Spell out numbers less than 10, except for percentages, time and versions.
    • Numbers in sentences are more difficult to read.
  • Capitalize “Crossplane” and “Kubernetes.”
    • Crossplane and Kubernetes are proper nouns. Don’t use k8s.
  • Spell out the first use of an acronym unless it’s common to new Crossplane users. When in doubt, spell it out first.
    • Avoid assuming the reader already knows the background.
  • Don’t use cliches.
    • Cliches make writing sound unprofessional and aren’t internationally inclusive.
  • Use contractions for phrases like “do not,” “cannot,” “is not” and related terms.
    • It’s easy to miss “not” in “do not.” It’s hard to misunderstand “don’t.”
  • Don’t use Latin terms (i.e., e.g., etc.).
    • These terms are more difficult for non-Latin language speakers to understand.
  • Avoid gerund headings (-ing words).
    • Gerunds make headings less direct.
  • Try and limit sentences to 25 words or fewer.
    • Longer sentences are more difficult to read. Shorter sentences are better for search engine optimization.
  • Be descriptive in link text. Don’t use “click here” or “read more”.
    • Describe link text improves accessibility for screen readers.
  • Order brand names alphabetically. For example, AWS, Azure, GCP.
    • Ordered names removes the appearance of preference.
  • Don’t use “easy,” “simple,” or “obvious”.
    • It’s condescending to the reader.
  • No Oxford commas.
    • A subjective style choice. No commas before “and” or “or.”
  • U.S. English spelling and grammar.

Crossplane relies on Vale to enforce the complete style guide.

Read more about using Vale with the Crossplane documentation.

Italics

Use italics to introduce or draw attention term.

Use italics on the same term sparingly.

Inline code styles

Use inline code styles, single ticks (`) for files directories or paths.

Use the {{< hover >}} shortcode to relate command explanations to larger examples.

Placeholders

Use angle brackets (< >) for placeholders. Use a short, descriptive name inside the brackets. Use underscores between words to simplify selections.

For example, to creating AWS credentials prompts for the key and secret key.

1[default]
2aws_access_key_id = <aws_access_key>
3aws_secret_access_key = <aws_secret_key>

Styling Kubernetes objects

Kinds

Kinds should be upper camel case. Capitalize each word, without separators.

For example the kind: MyComputeResource capitalizes “My,” “Compute” and “Resource” with no spaces or dashes.

1spec:
2  group: test.example.org
3  names:
4    kind: MyComputeResource

Names

Object names should use snake case. All words are lowercase with dashes (-) between them.

For example the name: my-resource uses all lowercase. A dash separates “my” and “resource.”

1apiVersion: test.example.org/v1alpha1
2kind: MyComputeResource
3metadata:
4  name: my-resource

Inline

Kubernetes objects mentioned inline don’t require styling unless drawing special attention.