Writing style guide for documentation and blog posts (WIP)
This is not an exhaustive or thorough explanation of the Metabase "brand voice," but some quick, overall guidelines for how our writing should feel.
- Friendly, but not peppy. Use exclamation points sparingly and judiciously.
- Casual, not formal. Say "can't" rather than "cannot." Say "give it a try" rather than "you may attempt this method if you so choose."
- Occasionally clever; never jokey. Don't rely on tired tropes about "nerdiness."
Page titles should be # h1s.
Headings should use sentence case rather than title case, and should not end with punctuation with the exception of a question mark if required. Even if a subheading precedes a list, do not use a colon.
Right: Here is my great heading
Wrong: This Is a Morally Inferior Heading.
Also wrong: Here is a heading before a list:
Keep your headings short; no more than about seven words.
Right: Setting up SAML-based authentication
Wrong: In this guide we'll show you how to set up authentication with SAML
Headings should not contain hyperlinks if it can possibly be avoided, unless the entire heading is a link. Instead, find a way to incorporate the link into the paragraph following the heading.
Acceptable: Running the Jar file
Wrong: Running Metabase on Heroku
Always strive to have the text that you wrap in an anchor tag be descriptive of where the link will take you. Avoid having links on the word "here." This makes it far easier for readers to scan through a page's links to find what they're looking for.
Right: If you need help, check out the SAML documentation.
Wrong: You can read the SAML documentation here or the SSO docs here.
- If any item in a list (ordered or not) forms a complete sentence, all items must begin with a capital letter and end with a terminal punctuation mark.
- If no items in an unordered list form a complete sentence, skip the capitalization and terminal punctuation.
Back-ticks should be used in docs only when writing out a section of code, or the name of a variable or parameter. They should not be used when referencing the label or string of a part of the UI, and should not be thought of as a substitute for quotation marks.
Right: Next, click on the "Done" button to set the value for
userAttribute.
Wrong: Next, click on the
Donebutton to set the value for userAttribute.
In general, use italics rather than bold in the middle of sentences to stress that a word is important. Bold text can be used when trying to call out important terms used in the explanation of a concept:
If you want to filter your question, first click the "Filter" button in the top-right.
Bold can be used to style lower-level headings or as a way to call out an important note. Example:
Important note: this feature does not work with MongoDB, even with the Enterprise Edition.
Generally, write out the word for the numbers zero to nine; after that, use numerals. E.g., "We've found three examples of companies who have more than 50 users." An exception is you should write out the word "hundreds" or "thousands," like "we have hundreds of options;" not like "we have 100s of options."
Unless you're writing out a code block, punctuation should always be contained inside of quotation marks. E.g., this is correct:
Did the user say "inconceivable," or "incontrovertible?"
E.g., "I would like to make apple, raspberry and blueberry, and peach pies for the festival."
Hyphens are primarily used when forming compound adjectives, e.g. "a long-overdue meeting."
Em dashes can be used as a break in a sentence or as a parenthetical, and should have a space before and after. E.g., "This is why Metabase — and other open source products — are so great."
Lastly, use an en dash when indicating a numeric range, and don't put spaces around them. E.g. "This feature was present in versions 20–33."
Only use these when they're part of a proper noun, like "Bourbon & Branch," never as a substitute for the word "and."
Check out The Elements of Typographic Style.
- Backend
- Metabase Developer Reference
- Product Management
- QA and Testing
- Writing A Driver
- Driver Notices
- REST API Notices
- Writing style guide for documentation and blog posts (WIP)