Documentation style guide

We don’t have an official style guide yet, but the current OpenTelemetry documentation style is inspired by the following style guides:

• Google Developer Documentation Style Guide
• Kubernetes Style Guide

The following sections contain guidance that is specific to the OpenTelemetry project.

OpenTelemetry.io word list

A list of OpenTelemetry-specific terms and words to be used consistently across the site:

• OpenTelemetry and OTel
• Collector
• OTEP
• OpAMP

For a complete list of OpenTelemetry terms and their definition, see Glossary.

Make sure that proper nouns, such as other CNCF projects or third-party tools, are properly written and use the original capitalization. For example, write “PostgreSQL” instead of “postgre”. For a full list, check the .textlintrc.yml file.

Markdown standards

To enforce standards and consistency for Markdown files, all files should follow certain rules, enforced by markdownlint. For a full list, check the .markdownlint.json file.

We also enforce Markdown file format and strip files of trailing whitespace. This precludes the line break syntax of 2+ spaces; use <br> instead or reformat your text.

Spell checking

Use CSpell to make sure that all your text is spelled correctly. For a list of words that are specific to the OpenTelemetry website, see the .cspell.yml file.

If cspell indicates an Unknown word error, verify if you wrote that word correctly. If so, add this word to the cSpell:ignore section at the top of your file. If no such section exists, you can add it to the front matter of a Markdown file:

---
title: PageTitle
cSpell:ignore: <word>
---

For any other file, add cSpell:ignore <word> in a comment line appropriate for the file’s context. For a registry entry YAML file, it might look like this:

# cSpell:ignore <word>
title: registryEntryTitle

File format

We enforce file formatting using Prettier. Invoke it using npm run fix:format.

File names

All file names should be in kebab case.

Fixing validation issues

To learn how to fix validation issues, see Pull request checks.