paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 21 Packages Projects Releases Wiki Activity

Merge branch 'master' into docs/golden-path-permissions

Browse Source
This commit is contained in:
Peter Macdonald
2026-03-24 16:06:22 +01:00
parent f34dc2a6f3 e0209029d6
commit a8e111f9b5
12 changed files with 477 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contribute/doc-style-guide.md
+334
View File
@@ -0,0 +1,334 @@
---
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.
## 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.
### 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. | |
docs/golden-path/plugins/sustainable-plugin-development.md
+38 -8
View File
@@ -8,23 +8,53 @@ description: Best practices for maintaining and iterating on Backstage plugins l
Plugins are not created in a vacuum, they generally solve a customer ask, be that
- a business problem, like showing cloud spend
- a new integration, like showing data from an external vendor such as Pagerduty
- a new integration, like showing data from an external vendor such as PagerDuty
- a developer pain point, like organizing information from disjoint or disorganized systems.
To ensure that your plugin lives the test of time, you'll need to figure out how to keep it up-to-date,
### Finding your stakeholders
## Finding your stakeholders
<!-- TODO -->
Your internal developer teams are your customers. They are the ones who will use your plugin day-to-day, and they are the best source of truth for whether it's solving the right problems. Before writing a single line of code, it's worth spending time talking to them.
### Iterating on your plugin
Start by identifying which teams are most affected by the problem you're trying to solve. If you're building a cloud spend plugin, talk to the teams who own cloud infrastructure. If you're consolidating on-call information, find the teams that own your incident response process. These are your primary stakeholders.
In many cases, your first version of a plugin will cut a few corners - this is a good sign, you're more focused on delivering a strong use case to continue development than over-indexing on your initial code. It may be temporary after all, if you don't get the response you're looking for!
When you meet with them, listen for:
- **Pain points**: What manual steps are slowing them down? What information do they have to hunt for across multiple tools?
- **Frequency**: How often do they hit this problem? A daily frustration is worth more investment than a quarterly one.
- **Workarounds**: What are they doing today instead? Existing workarounds often reveal what the minimum viable solution needs to cover.
Secondary stakeholders like platform teams, engineering managers, or team leads can give you a broader view of organizational needs and help you prioritize across teams. They can also act as champions who drive adoption once your plugin ships.
Keep these conversations ongoing. A quick check-in after you ship an early version is often more valuable than a long requirements-gathering session upfront. Your stakeholders will give you much clearer feedback once they've seen something working.
## Iterating on your plugin
In many cases, your first version of a plugin will cut a few corners. This is a good sign; you're more focused on delivering a strong use case to continue development than over-indexing on your initial code. It may be temporary after all, if you don't get the response you're looking for!
So, how do you decide when you should iterate on your plugin?
<!-- TODO -->
The clearest signal is feedback from the teams using it. Go back to the stakeholders you identified earlier. Are they actually using the plugin? Are they hitting friction you didn't anticipate? Direct conversations and usage patterns will tell you far more than assumptions made during initial development.
### Ensuring the success of your plugin
Some common triggers for iteration:
<!-- TODO -->
- **Stakeholder feedback reveals a gap**: A team is using your plugin but still switching to another tool for one specific thing. That gap is your next iteration.
- **Adoption is lower than expected**: If teams aren't using it, find out why before adding features. The problem is often discoverability, missing context, or a workflow mismatch rather than missing functionality.
- **The underlying data or service has changed**: External systems evolve. If your plugin surfaces data from another service, keep a line open with the team that owns it so you're not caught off guard.
- **Analytics surface unexpected patterns**: Backstage has built-in support for analytics events. If you've instrumented your plugin, usage data can reveal which parts of your plugin are heavily used, which are ignored, and where users drop off. A page with high traffic but short visit times might indicate users aren't finding what they need.
Not every piece of feedback warrants an immediate change. Weigh requests against how broadly they apply; a request from one team may not justify the complexity it adds for everyone else. Your stakeholders are your best guide for prioritization here too.
## Ensuring the success of your plugin
A successful plugin is one that continues to be used, trusted, and improved over time. That doesn't happen by accident. It's the result of staying connected to the people who depend on it.
The foundations are straightforward:
- **Keep your stakeholder relationships active.** Don't treat the initial conversations as a one-time exercise. Check in regularly, especially after shipping new versions. The teams using your plugin are the fastest way to find out what's working and what isn't.
- **Let feedback drive your priorities.** It can be tempting to iterate on the parts of your plugin you find most interesting technically. Let usage patterns and stakeholder feedback anchor your roadmap instead.
- **Instrument your plugin.** Analytics give you signal between conversations. If a feature is being ignored, or a page has high drop-off, that's worth investigating before investing further in that direction.
- **Treat it like a product, not a project.** A plugin that ships and gets abandoned quickly loses the trust of its users. Even small, regular improvements signal that the plugin is maintained and worth relying on.
The common thread across all of this is that your developers are your customers. Keeping that relationship healthy is what separates a plugin that becomes a critical part of your developer portal from one that quietly gets bypassed.