---
id: doc-style-guide
title: Documentation Style Guide
description: Writing style guidelines for Backstage documentation
---

This page gives writing style guidelines for the Backstage documentation.
These are guidelines, not rules. Use your best judgment, and feel free to
propose changes to this document in a pull request.

For additional information on contributing to the docs, see the
[Contributors Guide](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md#documentation-guidelines).

## Language

Backstage documentation uses U.S. English spelling and grammar.

The documentation site is built with [Docusaurus](https://docusaurus.io/) and
uses standard Markdown with some Docusaurus-specific features like
[admonitions](https://docusaurus.io/docs/markdown-features/admonitions).

## Tone

Backstage documentation should feel approachable, professional, and helpful.
Write as if you are a knowledgeable colleague explaining something to a peer
who is new to the topic but not new to software development.

- **Be friendly but not casual.** Avoid slang, humor that might not translate,
  or overly enthusiastic language. A warm, straightforward tone works best.
- **Be respectful of the reader's time.** Get to the point. If a concept needs
  a longer explanation, provide it, but don't pad content with filler.
- **Be encouraging without being patronizing.** Assume the reader is competent.
  Avoid phrases like "as everyone knows" or "obviously."
- **Be inclusive.** Use gender-neutral language. Avoid cultural references that
  might not be understood globally. Write for an international audience.
- **Be precise.** Use the correct technical terminology for Backstage concepts.
  When introducing a new term, define it on first use.

## Documentation formatting standards

### Use bold for user interface elements

| Do                | Don't           |
| :---------------- | :-------------- |
| Click **Fork**.   | Click "Fork".   |
| Select **Other**. | Select "Other". |

### Use italics to define or introduce new terms

| Do                                          | Don't                                         |
| :------------------------------------------ | :-------------------------------------------- |
| A _plugin_ is a modular extension ...       | A "plugin" is a modular extension ...         |
| These components form the _backend system_. | These components form the **backend system**. |

### Use code style for filenames, directories, and paths

| Do                                             | Don't                                        |
| :--------------------------------------------- | :------------------------------------------- |
| Open the `app-config.yaml` file.               | Open the app-config.yaml file.               |
| Go to the `/plugins` directory.                | Go to the /plugins directory.                |
| Open the `packages/backend/src/index.ts` file. | Open the packages/backend/src/index.ts file. |

### Use code style for inline code and commands

| Do                                                                         | Don't                                                                |
| :------------------------------------------------------------------------- | :------------------------------------------------------------------- |
| The `yarn start` command starts the app.                                   | The "yarn start" command starts the app.                             |
| Run `yarn install` from the project root.                                  | Run "yarn install" from the project root.                            |
| Use single backticks to enclose inline code, for example `const x = true`. | Use bold or italics for inline code, for example **const x = true**. |
| Enclose code samples with triple backticks.                                | Enclose code samples with any other syntax.                          |
| Use meaningful variable names that have context.                           | Use variable names such as `foo`, `bar`, and `baz`.                  |

### Use code style for package names and API references

<!-- vale off -->

| Do                                                               | Don't                                                            |
| :--------------------------------------------------------------- | :--------------------------------------------------------------- |
| Install the `@backstage/core-plugin-api` package.                | Install the @backstage/core-plugin-api package.                  |
| The `createRouter` function creates a new router.                | The createRouter function creates a new router.                  |
| Set the value of the `backend.baseUrl` field in the config file. | Set the value of the "backend.baseUrl" field in the config file. |

<!-- vale on -->

### Use angle brackets for placeholders

Use angle brackets for placeholders. Tell the reader what a placeholder
represents. For example:

```shell
yarn workspace @backstage/plugin-<plugin-name> start
```

### Use the international standard for punctuation inside quotes

| Do                                              | Don't                                           |
| :---------------------------------------------- | :---------------------------------------------- |
| Events are recorded with an associated "stage". | Events are recorded with an associated "stage." |
| The copy is called a "fork".                    | The copy is called a "fork."                    |

## Code snippet formatting

### Don't include the command prompt

| Do             | Don't            |
| :------------- | :--------------- |
| `yarn install` | `$ yarn install` |

### Separate commands from output

Verify that the app is running:

```shell
yarn start
```

The output is similar to this:

```console
[0] webpack output is served from /
[1] Loaded config from app-config.yaml
```

### Use appropriate language tags for code blocks

Use the correct language identifier for fenced code blocks: `ts` or `typescript`
for TypeScript, `yaml` for YAML configuration, `shell` for shell commands,
`console` for command output, and `diff` for changesets.

## Admonitions

Backstage documentation uses
[Docusaurus admonitions](https://docusaurus.io/docs/markdown-features/admonitions)
for callouts. Use `:::note`, `:::tip`, `:::caution`, and `:::danger` as
appropriate.

```markdown
:::note
You can use _Markdown_ inside admonitions.
:::
```

:::note
You can use _Markdown_ inside admonitions.
:::

Use `:::note` for supplementary information, `:::tip` for helpful suggestions,
`:::caution` for potential pitfalls, and `:::danger` for actions that could
cause data loss or security issues.

Keep admonitions short and focused. Each admonition should contain a single,
clear point. If you find yourself writing multiple paragraphs inside an
admonition, consider whether the content belongs in the main text instead.

Avoid stacking multiple admonitions in a row. Too many callouts on a page
dilute their impact and make the content harder to read. If a section has
more than two admonitions, restructure the content so that most of the
information is in regular paragraphs.

## Accordions

Use HTML `<details>` and `<summary>` elements to create collapsible sections.
These are useful for "Common issues" sections, lengthy reference tables, or
supplementary content that would otherwise break the reading flow.

```markdown
<details>
  <summary>Summary text visible when collapsed</summary>

Content inside the accordion. You can use **Markdown** here, including code
blocks, lists, and other formatting.

</details>
```

<details>
  <summary>Summary text visible when collapsed</summary>

Content inside the accordion. You can use **Markdown** here, including code
blocks, lists, and other formatting.

</details>

Leave a blank line after the `<summary>` tag and before the closing
`</details>` tag so that Markdown content inside renders correctly.

Use backticks for inline code inside `<summary>` elements instead of HTML
`<code>` tags. Backticks render correctly inside summary elements and keep
the source consistent with the rest of the Markdown content.

## Markdown elements

### Line breaks

Use a single newline to separate block-level content like headings, lists,
images, code blocks, and others. Manually wrap paragraphs in the Markdown
source at a reasonable line length. This makes diffs easier to review and
helps downstream localization.

### Headings and titles

| Do                                                                        | Don't                                                                  |
| :------------------------------------------------------------------------ | :--------------------------------------------------------------------- |
| Use ordered headings to provide a meaningful outline of your content.     | Use headings level 4 through 6 unless absolutely necessary.            |
| Use sentence case for headings. For example, **Extend the catalog model** | Use title case for headings. For example, **Extend The Catalog Model** |
| Use pound signs (`#`) for headings.                                       | Use underlines (`---` or `===`) for headings.                          |

### Paragraphs

| Do                                                          | Don't                                |
| :---------------------------------------------------------- | :----------------------------------- |
| Try to keep paragraphs under 6 sentences.                   | Write long, unbroken walls of text.  |
| Use three hyphens (`---`) for horizontal rules when needed. | Use horizontal rules for decoration. |

### Links

| Do                                                                                                                   | Don't                                                                                      |
| :------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- |
| Write hyperlinks with descriptive text. For example: See [Getting Started](../getting-started/index.md) for details. | Use ambiguous link text. For example: See [here](../getting-started/index.md) for details. |
| Write Markdown-style links: `[link text](./index.md)`.                                                               | Write HTML-style links or create links that open in new tabs.                              |

### Lists

- End each item in a list with a period if one or more items in the list are
  complete sentences. For consistency, either all items or none should be
  complete sentences.
- Use the number one (`1.`) for ordered lists.
- Use (`-`) for unordered lists.
- Leave a blank line after each list.
- Indent nested lists with two spaces.
- Use a numbered list for a sequence of steps rather than prose with
  "First", "Then", and "Finally". Numbered lists are easier to scan, make
  the order explicit, and give readers a clear way to reference a specific
  step.

| Do                                                                 | Don't                                                                           |
| :----------------------------------------------------------------- | :------------------------------------------------------------------------------ |
| 1) Install the package. 2) Run the migration. 3) Start the server. | First, install the package. Then, run the migration. Finally, start the server. |

### Tables

Use Markdown tables with clear column headers. Keep table content concise.
For large amounts of structured data, consider using a list or separate
subsections instead.

## Content best practices

### Spell out acronyms on first use

When using an acronym, spell it out in full on first use followed by the
acronym in parentheses. After that, you can use the acronym alone.

| Do                                                      | Don't                                 |
| :------------------------------------------------------ | :------------------------------------ |
| Software Development Kit (SDK)                          | SDK (without ever defining it)        |
| Role-Based Access Control (RBAC) ... configure RBAC ... | RBAC ... configure RBAC ...           |
| Hyper Text Markup Language (HTML)                       | HTML (on first use without expansion) |

Exception: Universally understood acronyms like URL, API, or HTML do not
need to be spelled out if they are common knowledge for the target audience
of software developers.

### Use present tense

| Do                                  | Don't                                   |
| :---------------------------------- | :-------------------------------------- |
| This command starts a proxy.        | This command will start a proxy.        |
| The plugin provides a catalog page. | The plugin will provide a catalog page. |

Exception: Use future or past tense if it is required to convey the correct
meaning.

### Use active voice

| Do                                       | Don't                                       |
| :--------------------------------------- | :------------------------------------------ |
| You can explore the API using a browser. | The API can be explored using a browser.    |
| The YAML file specifies the base URL.    | The base URL is specified in the YAML file. |

Exception: Use passive voice if active voice leads to an awkward construction.

### Use simple and direct language

| Do                          | Don't                                                    |
| :-------------------------- | :------------------------------------------------------- |
| To create a plugin, ...     | In order to create a plugin, ...                         |
| See the configuration file. | Please see the configuration file.                       |
| View the catalog entities.  | With this next command, we'll view the catalog entities. |

### Address the reader as "you"

| Do                                       | Don't                                   |
| :--------------------------------------- | :-------------------------------------- |
| You can create a plugin by ...           | We'll create a plugin by ...            |
| In the preceding output, you can see ... | In the preceding output, we can see ... |

### Avoid Latin phrases

Prefer English terms over Latin abbreviations.

| Do               | Don't     |
| :--------------- | :-------- |
| For example, ... | e.g., ... |
| That is, ...     | i.e., ... |

Exception: Use "etc." for and so on.

## Patterns to avoid

### Be intentional with "we"

"We" is fine in tutorials and walkthroughs where it means "you and I, working
through this together." Avoid "we" when it's unclear whether it refers to the
Backstage project, the maintainers, or the reader's team.

| Ok                                          | Avoid                              |
| :------------------------------------------ | :--------------------------------- |
| Next, we need to add the backend package.   | We provide a new feature ...       |
| We can verify this by running `yarn start`. | In version 1.25, we have added ... |

### Avoid jargon and idioms

Some readers speak English as a second language. Avoid jargon and idioms to
help them understand better.

| Do                   | Don't                 |
| :------------------- | :-------------------- |
| Internally, ...      | Under the hood, ...   |
| Create a new plugin. | Spin up a new plugin. |

### Avoid statements about the future

Avoid making promises or giving hints about the future. If you need to talk
about an experimental feature, clearly label it as such.

### Avoid statements that will soon be out of date

Avoid words like "currently" and "new." A feature that is new today might not
be considered new in a few months.

| Do                              | Don't                               |
| :------------------------------ | :---------------------------------- |
| In version 1.25, ...            | In the current version, ...         |
| The search feature provides ... | The new search feature provides ... |

### Avoid words that assume a specific level of understanding

Avoid words such as "just", "simply", "easy", "easily", or "simple". These
words do not add value.

| Do                         | Don't                           |
| :------------------------- | :------------------------------ |
| Include one command in ... | Include just one command in ... |
| Run the container ...      | Simply run the container ...    |
| You can remove ...         | You can easily remove ...       |
| These steps ...            | These simple steps ...          |

## Backstage word list

A list of Backstage-specific terms and words to be used consistently across
the site.

| Term               | Usage                                                                                                                                  |
| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| Backstage          | Always capitalized.                                                                                                                    |
| plugin             | Lowercase when referring to the concept. Use code style when referring to a specific package, for example `@backstage/plugin-catalog`. |
| Software Catalog   | Capitalized as a product name. Use "catalog" (lowercase) when referring to the concept generically.                                    |
| Software Templates | Capitalized as a product name.                                                                                                         |
| TechDocs           | One word, camel case.                                                                                                                  |
| Scaffolder         | Capitalized as a product name.                                                                                                         |
| app-config         | Use code style: `app-config.yaml`.                                                                                                     |
| open source        | Two words, lowercase (unless starting a sentence).                                                                                     |
| backend system     | Lowercase when referring to the Backstage backend framework.                                                                           |

## General word list

A list of general terms and words to be used consistently across the site.

| Term   | Usage                                                           |
| :----- | :-------------------------------------------------------------- |
| GitHub | Use GitHub in documentation. In code, use `github` (lowercase). |