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:
The following sections contain guidance that is specific to the OpenTelemetry project.
Note
Many requirements of our style guide can be enforced by running automation:
before submitting a
pull request
(PR), run npm run fix:all on your local machine and commit the changes.
If you run into errors or failed PR checks, read about our style guide below and what you can do to fix certain common issues.
OpenTelemetry.io word list
A list of OpenTelemetry-specific terms and words to be used consistently across the site.
| Term | Usage |
|---|---|
| OpenTelemetry | OpenTelemetry should always be capitalized. Don’t use Open-Telemetry. |
| OTel | OTel is the accepted short form of OpenTelemetry. Don’t use OTEL. |
| Collector | When referring to the OpenTelemetry Collector, always capitalize Collector. |
| OTEP | OpenTelemetry Enhancement Proposal. Write “OTEPs” as plural form. Don’t write “OTep” or “otep”. |
| OpAMP | Open 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 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 fix:filenames to automatically rename your files.