Style guide

The voice for our technical documentation is concise, direct, and precise. The goal is to provide information that's easy to search and scan. The voice in the documentation should be conversational but brief, friendly but succinct.

Rather than write our own style guide—follow the existing industry best practices for writing technical documentation. A great resource is the Google developer documentation style guide. Another great resource is the diataxis style guide.

At a high level:

• Avoid unnecessary words.
• Be clear, concise, and stick to the goal of the topic.
• Write in British English.
• Use the active voice.
• In steps, bold things users do or click on.
• In text use backticks for code, terminal commands, filenames, and folders.
• Use contractions, they create a friendly and informal tone, especially in tutorials and instructional docs.
• Use Oxford commas in comma separated lists of three or more items.
• Please do reference existing product documentation—but highlight where users have to do things differently for our project.
• Page file names use kebab case names (e.g. log-collection.mdx).
• Pages declare a title and use sentence case (as opposed to title case), e.g.

  ---
  title: How to configure log collection
  ---

• Use conventional commit messages when committing changes to the documentation. This helps with generating changelogs and release notes. See Conventional Commits.

Documentation is the single source of truth (SSoT)

The technical documentation is the SSoT for all product information related to implementation, use, and troubleshooting. The documentation evolves continuously. It's updated with new products and features, and with improvements for clarity, accuracy, and completeness.

Tools to help you

If you write in VS Code, you can install the Vale on your machine.