---
title: "Docs style guide"
url: "https://docs.yugabyte.com/stable/contribute/docs/docs-style/"
---

# Docs style guide

YugabyteDB documentation style guide

The YugabyteDB documentation style is based on the [Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/welcome/ "Microsoft style guide"), with some input from [Apple's style guide](https://help.apple.com/applestyleguide/#/ "Apple's style guide"). We aim to automate as much as possible through Vale.

## Conventions

👉 There are always exceptions. Use your best judgement; clarity should always win over compliance with (at least *most of*) the rules.

### Voice

Yugabyte's documentation voice should be informal and authoritative. Speak (or rather, write) plainly, address the reader directly, and tell them what they need to know.

**Use second person.** Address the reader directly: "Before you start, make sure your VM is configured as follows."

**Active voice.** There are rare times when a passive construction is a lot less convoluted.

**Contractions.** They're good. Don't use them in a legal contract, but do use them most other places.

### Headings

**Sentence case.** "Provision your cluster", not "Provision Your Cluster". Obvious exceptions include proper nouns, product names, and more.

**Avoid numbered headings.** Occasionally, it might make sense to add numbers to headings, but in general, avoid it. It's a common error to delete a section and forget to re-number the ones that follow; and even if you do remember, manual re-numbering is just a nuisance. (This is the main reason for auto-numbering ordered lists, too!)

**Don't use terminal punctuation.** Headings don't need end punctuation, except run-in headings like these. And if your heading is a complete sentence, consider shortening it.

**Use imperative headings.** They're more of a call to action than gerunds. "Provision your cluster" makes it clear this is something *you the reader* are going to do, rather than "Provisioning your cluster". Gerunds and other constructions will sometimes be clearer, so don't feel obligated to use an imperative where it really doesn't work.

### Links

Prefer markdown-style `[link text](/stable/contribute/docs/docs-style/link-target)` links over HTML tags. Markdown's endnote-style links are also fine to use. Hugo has its own curly-brace link syntax, but it's less friendly and doesn't seem to have many advantages in normal use.

### Code blocks

**Code language is required.** Every code block needs a language tag. Use `output` for all output, and append a language if you want to have source highlighting but still omit the Copy button (for example, `output.json`). The Hugo docs list [all language names](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages "all language names") you can use for fenced code blocks.

**Prompts may be necessary.** In a given procedure, the first code block should show the prompt; subsequent blocks can omit it, provided it doesn't impact clarity. Don't omit prompts (particularly shell prompts) if a procedure takes input in more than one way, such as an operation in ysqlsh followed by one in bash.

You can use the following attributes to modify code blocks:

- **Highlight bad code.** To highlight wrong coding practices, add the attribute `{.badcode}` to the code block. For example, `sql{.badcode}`:
  
  ```sql
  ysqlsh> CREATE TABLE $$__banking__$$;
  ```
- **Remove the copy button.** To remove the Copy button from any code block, add the attribute `{.nocopy}` to the code block. For example, `sql{.nocopy}`:
  
  ```sql
  CREATE TABLE users(id INT PRIMARY KEY, name TEXT);
  ```

#### YSQL and YCQL code blocks

Tag YSQL code blocks as `plpgsql`, and YCQL code blocks as `cql`. The source highlighting differs slightly between the two.

### Admonitions

Use admonitions sparingly. They lose their effectiveness if they appear too often. Avoid multiple admonitions in a row, and in most cases don't place them immediately after a heading.

To insert an admonition (a tip, note, or warning box), see [Widgets and shortcodes](/stable/contribute/docs/widgets-and-shortcodes/#admonition-boxes "Widgets and shortcodes").

## Markdown linting

Use `markdownlint` to find and fix Markdown problems locally before you push a commit. There's a command-line utility available through Homebrew, and there are also extensions available for several editors, including Visual Studio Code. Markdownlint's [rules are well-documented](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md "rules are well-documented").

## Prose linting with Vale

We aim to use [Vale](https://docs.errata.ai "Vale") to reinforce as many of the style-guide conventions as possible.

You can run Vale locally in two ways: in a supported editor, and from the command line. Either way you run it, it'll pick up the configuration from [`/docs/.vale.ini`](https://github.com/yugabyte/yugabyte-db/blob/master/docs/.vale.ini "/docs/.vale.ini") in the main repository.

**To run Vale from the command line** (there are more options than this!):

1. `brew install vale`
2. `vale <filename>` or `vale <foldername>`

For example, `vale docs/` or `vale yb-docs-style-guide.md`.

**To run Vale in Visual Studio Code**:

1. `brew install vale` (Even running in the editor, you still need the CLI installed.)
2. In Visual Studio Code, find and install the `Vale` extension from errata-ai.
3. Configure the extension: check the Vale &gt; Core &gt; Use CLI checkbox.
4. Restart Visual Studio Code.

Installed in this way, Vale lints the current file every time you save it.