Documentation Style Guide

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.

Language

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

The documentation site is built with Docusaurus and uses standard Markdown with some Docusaurus-specific features like 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

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.

Use angle brackets for placeholders

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

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:

yarn start

The output is similar to this:

[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 for callouts. Use :::note, :::tip, :::caution, and :::danger as appropriate.

:::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.

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 for details.	Use ambiguous link text. For example: See here 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.

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. | |