Docs style guide
👉 There are always exceptions. Use your best judgement; clarity should always win over compliance with (at least most of) the rules.
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.
Sentence case. For example, "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.
[link text](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 any advantages in normal use.
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 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.
YSQL and YCQL code blocks
Tag YSQL code blocks as
sql, and YCQL code blocks as
cql. The source highlighting differs slightly between the two.
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.
Prose linting with Vale
We aim to use 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 in the main repository.
To run Vale from the command line (there are more options than this!):
brew install vale
vale docs/ or
To run Vale in Visual Studio Code:
brew install vale(Even running in the editor, you still need the CLI installed.)
- In Visual Studio Code, find and install the
Valeextension from errata-ai.
- Configure the extension: check the Vale > Core > Use CLI checkbox.
- Restart Visual Studio Code.
Installed in this way, Vale lints the current file every time you save it.