Skip to main content

Solus style guide

Solus needs a style guide to give clarity to our contributors and a consistent experience for readers. But we don't want to write our own! We surveyed existing style guides, and we picked parts that were more suitable for our content.

note

Existing help center topics might not follow our style guide yet.

General writing style​

Use the Google developer documentation style guide for general writing style, grammar, and formatting.

Some useful pages:

Linux-specific terms​

If you are unsure of how to use a common Linux term, refer to the Glossary of terms and conventions from the Red Hat supplementary style guide for documentation

Specific guidance​

In alphabetical order, not order of importance.

Admonitions​

This section is based on the Red Hat supplementary style guide.

Admonitions should draw the reader’s attention to certain information. Keep admonitions to a minimum, and avoid placing multiple admonitions close to one another. If multiple admonitions are necessary, restructure the information by moving the less-important statements into the flow of the main content. See the Docusaurus documentation to learn the correct syntax.

TypeDescription
NoteAdditional guidance or advice that improves product configuration, performance, or supportability
TipRecommendations, suggestions, and alternative methods that might not be obvious. Tips are not essential to using the product.
InfoGeneral information about the topic at hand that may be useful or relevant to user.
ImportantAdvisory information essential to the completion of a task or default configuration settings. Users must not disregard this information.
WarningInformation that warns the user to proceed with caution. Warning emphasizes a course of action’s potential downsides.
DangerInformation about imminent system damage, data loss, or a support-related issue if the user disregards this admonition. If available, offer information to avoid the problem in the future or state where to find more information.

Code blocks​

Code blocks must indicate the programming language of the code snippet.

```js
console.log("Hello, world!");
```

Commands​

  • Commands as part of procedures must be inside code blocks with bash as the language type. This ensures users get a "copy to clipboard" button.

  • When needed, indicate the directory where users need to move before executing the command.

    ```bash
    cd  ~/path/to/directory
    sudo somecommand
    ```

Common Solus terms​

  • Solus
    • Prefer Solus rather than Solus Project. Don't use Solus OS or Solus Linux.
    • The names of the different editions of Solus are:
      • Solus Budgie
      • Solus GNOME
      • Solus Plasma
      • Solus XFCE
  • Repositories
    • Avoid using terms such as repo, or monorepo, use the specific repository name instead.
    • Example: "The packages repository", instead of "The monorepo".
  • Dev Tracker
    • Avoid using the term Dev Tracker.
    • Example: "The packages issue tracker", instead of "The dev tracker"

Markdown formatting​

Write content using markdown formatting, use Prettier to enforce consistent formatting.

Package Names​

  • The name of packages in the Solus repository must use inline code formatting.
To install `caddy`, use the Software Center or execute the following command:
  • When referring to the name of a product or project, use the name the authors use.

Examples: RetroArch, and Code::Blocks

Spelling​

We prefer American spelling over British spelling. When in doubt about the spelling of a word, see the Merriam-Webster dictionary.