Contributing Guide on Crossplane

Getting Started

The Crossplane documentation lives in the docs GitHub repository.

Local development

Clone the documentation and use Hugo to build the Crossplane documentation site locally for development and testing.

Clone the docs repository

Clone the Crossplane docs repository with

git clone https://github.com/crossplane/docs.git

Download Hugo

Download Hugo, the static site generator Crossplane docs uses.

Important

Download the hugo_extended version. The standard Hugo package doesn’t support the Crossplane docs CSS.

Extract and run Hugo with hugo server.

Writing Style Guide

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.

Using Vale

Crossplane relies on Vale to enforce the style guide.

Crossplane’s Vale style definitions are in the utils/vale directory.

Important

The Crossplane community is updating existing content to pass Vale. Until the community completes the project Vale errors are only enforced for new or changed content. The community approves PRs with Vale errors in unmodified document sections.

Install Vale

Follow the directions on the Vale website to install the Vale binary.

Code Styling Guide

To optimize readability and comprehension Crossplane has developed guidelines for source code used in documentation.

Use fenced code blocks

Use Markdown fenced code blocks with three backticks (```) for all command examples and outputs.

1```
2this is a code block
3```

Only use a single backtick (`) for commands used in a sentence.

For example, the command kubectl apply is inside a sentence.

Additional Styling Features

The following is a list of Crossplane documentation customizations that expand traditional Markdown. Most of these are custom Hugo Shortcodes.

Note

If you’re having trouble with the Hugo shortcodes, ask for help in the #documentation channel of the Crossplane Slack.

Markdown

Crossplane documentation uses Hugo to render Markdown to HTML. Hugo supports Commonmark and GitHub Flavored Markdown through the Goldmark parser.

Note

Commonmark and GFM are extensions to the standard Markdown language.

The docs support standard Markdown for images, links and tables, Crossplane recommend using the custom shortcodes to provide a better experience for readers.

Docs Infrastructure

The Crossplane document website is in a standalone GitHub repository separate from Crossplane core.

The Crossplane docs tools consist of:

Netlify - web hosting and DNS provided by the CNCF.
Hugo - to compile markdown to static HTML.
Bootstrap - for pre-built CSS options.
PostCSS - for CSS optimization.
Webpack - for Javascript optimization.

Netlify

Builds for production deploys and PR previews are automatically done by Netlify.