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.

Run:

• npm run check:markdown to ensure that all files follow our standards
• npm run fix:markdown to fix Markdown-related formatting issues

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.

Run npm run check:spelling to verify that all your words are spelled correctly. 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

Website tooling normalizes page-specific dictionaries (that is, the cSpell:ignore word lists), by removing duplicate words, deleting words in the global word list, and sorting words. To normalize page-specific dictionaries, run npm run fix:dict.

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. Run npm run fix:filenames to automatically rename your files.