Documentation style guide

Terminology and style when writing OpenTelemetry docs.

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

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.

TermUsage
OpenTelemetryOpenTelemetry should always be capitalized. Don’t use Open-Telemetry.
OTelOTel is the accepted short form of OpenTelemetry. Don’t use OTEL.
CollectorWhen referring to the OpenTelemetry Collector, always capitalize Collector. Write “The Collector” or “The Opentelemetry Collector” if you’re starting a sentence. Write “the Collector” or “the OpenTelemetry Collector” in the middle or end of a sentence. Use just “Collector” if you are using Collector as an adjective (for example, “Collector configuration”).
OTEPOpenTelemetry Enhancement Proposal. Write “OTEPs” as plural form. Don’t write “OTep” or “otep”.
OpAMPOpen Agent Management Protocol. Don’t write “OPAMP” or “opamp” in descriptions or instructions.

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.

See also the Glossary for a list of OpenTelemetry terms and their definition.

Run npm run check:text to verify that all terms and words are written properly.

Run npm run check:text -- --fix to fix terms and words that are not written properly.

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 verify that all files follow the standard.

Run npm run fix:markdown to fix Markdown related formatting issues.

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 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

To enforce a certain standard on how files are structured, all files should be formatted by prettier. Run npm run fix:format before submitting a PR, or run it afterwards and push an additional commit.

File names

All file names should be in kebab case. Run npm run fix:filenames to automatically rename your files.