Writing Style Guide

Use this style guide as a check list when reviewing / writing:

• documentation
• blog posts
• posts on social media

Objective

In our written communication we aim to be:

• concise: It's common to skim through text these days.
• easily understood: Simple terms, phrases, and words reach a wider audience.
• informal: We're not a big corporation, we need to appear as a small, human company.

Guidance

1. Use contractions: Avoid: "We are proud to announce ..." Use: "We're proud to announce ..." Rationale: Makes for a conversational, human tone.

2. Offer direct advice:

• Avoid: "Please install XYZ ..."
• Use: "Install XYZ"
• Rational: The user is reading this to get instructions, there's no need to beat around the bush.

3. Write actionable:

• Avoid: "Element XYZ makes it possible to set the background color."
• Use: "Use element XYZ to set the background color."
• Rationale: Shorter, straight to the point.

4. Don't shout.

• Avoid: "Try out XYZ!"
• Use: "Try out XYZ."
• Rationale: Use exclamation points sparingly, save them for when they really count. We already have the attention of the reader.

5. Use Title Case for headings.

6. Use active voice for things we did, for example in blog posts.

• Avoid: "The foo widget got revamped."
• Use: "We revamped the foo widget."
• Rationale: We're not joining the audience on the observer's bench, we're announcing the result of our work.

7. User-Centric Messaging: Write from the user's perspective. Emphasize the value or outcome a user gains rather than focusing on product changes.

• Avoid: "Slint adds feature X."
• Use: "Achieve Y using the new X feature in Slint."
• Rationale: Users care about how a feature helps them solve a problem or reach a goal—not just that it exists.

8. In Markdown (including in documentation comments), add a newline between sentences, or after a comma if the line is too long.

• Rationale: Just like we add a newline after ; in code, this helps create readable diffs and avoids reflowing a entire paragraph for every edit.

Docs

• Ensure links don't go to blank pages e.g. 1.7 concepts

Tabs

The dev-platform tabs should be in the following order:

• Windows
• macOS
• Linux
• Android
• iOS