From 7f26ea88c58c9e6f14d83a4c6b216c4f9260b412 Mon Sep 17 00:00:00 2001 From: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> Date: Tue, 24 Mar 2026 15:44:35 +0100 Subject: [PATCH] docs: add documentation style guide for Backstage contributors (#33538) * docs: add documentation style guide for Backstage contributors Adapted from the Kubernetes documentation style guide, tailored for the Backstage project with Backstage-specific terminology, Docusaurus conventions, tone guidelines, and project word list. Co-Authored-By: Claude Opus 4.6 Signed-off-by: aramissennyeydd * docs: soften "we" guidance and link style guide from CONTRIBUTING.md Relax the "avoid we" rule to allow "we" in tutorials and walkthroughs where it means "you and I, working through this together." Also add references to the style guide from CONTRIBUTING.md and AGENTS.md. Co-Authored-By: Claude Opus 4.6 Signed-off-by: aramissennyeydd * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> * fix link checker Signed-off-by: aramissennyeydd * skip block Signed-off-by: aramissennyeydd * address feedback Signed-off-by: aramissennyeydd --------- Signed-off-by: aramissennyeydd Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../config/vocabularies/Backstage/accept.txt | 10 +- AGENTS.md | 6 +- CONTRIBUTING.md | 4 +- docs/contribute/doc-style-guide.md | 334 ++++++++++++++++++ microsite/sidebars.ts | 1 + 5 files changed, 349 insertions(+), 6 deletions(-) create mode 100644 docs/contribute/doc-style-guide.md diff --git a/.github/vale/config/vocabularies/Backstage/accept.txt b/.github/vale/config/vocabularies/Backstage/accept.txt index 30fd3e7311..5b9d088e23 100644 --- a/.github/vale/config/vocabularies/Backstage/accept.txt +++ b/.github/vale/config/vocabularies/Backstage/accept.txt @@ -49,6 +49,7 @@ bundler bundlers bursty callout +callouts camelCase CDNs Chai @@ -59,6 +60,7 @@ chanwit Chanwit CI/CD classname +cleye cli CLIs cloudbuild @@ -138,6 +140,7 @@ dyno ecco elasticsearch Entra +enums env Env esbuild @@ -248,6 +251,7 @@ lightbox Lightsail limitranges liveness +LLMs LocalStack lockdown lockfile @@ -394,6 +398,7 @@ repos requestors rerender rerenders +resizable resourcequotas retryable reusability @@ -562,6 +567,7 @@ VMware Vodafone VPCs VSCode +walkthroughs Wayfair Weaveworks Webpack @@ -580,7 +586,3 @@ zod Zolotusky zoomable zsh -resizable -enums -LLMs -cleye diff --git a/AGENTS.md b/AGENTS.md index 010ebca9e7..15de219e83 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,11 @@ Backstage is an open platform for building developer portals. This is a TypeScri - `/packages/backend`: Example backend for local development - `/docs`: Documentation files -Packages prefixed with `core-` (e.g., `@backstage/core-plugin-api`) are part of the old frontend system. Packages prefixed with `frontend-` (e.g., `@backstage/frontend-plugin-api`) are part of the new frontend system (NFS). Packages prefixed with `backend-` (e.g., `@backstage/backend-plugin-api`) are part of the backend system. +Packages prefixed with `core-` (e.g., `@backstage/core-plugin-api`) are part of the old frontend system. Packages prefixed with `frontend-` (e.g., `@backstage/frontend-plugin-api`) are part of the new frontend system. Packages prefixed with `backend-` (e.g., `@backstage/backend-plugin-api`) are part of the backend system. + +## Writing Standards + +Changes to the docs should follow the documentation style guide at `/docs/contribute/doc-style-guide.md`. ## Code Standards diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index adf04c48e2..5d01886873 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -170,7 +170,9 @@ To help your changes get reviewed and merged smoothly, please keep the following - We really appreciate contributions that improve clarity or fix outdated information. That said, we generally don’t accept changes that are purely stylistic (e.g., rewording a sentence just to tweak the tone or phrasing). If something is **unclear**, **confusing**, or **factually inaccurate**, those are great opportunities to help! -Ready to get started? You can find all the documentation files in the [docs](docs) directory! If you have any questions or need help, feel free to reach out in the [Backstage Discord Docs Channel](https://discord.com/channels/687207715902193673/687994765559463940) +Ready to get started? You can find all the documentation files in the [docs](docs) directory! +Please take a look through [our style guide](./docs/contribute/doc-style-guide.md) as well for writing style tips. +If you have any questions or need help, feel free to reach out in the [Backstage Discord Docs Channel](https://discord.com/channels/687207715902193673/687994765559463940). Thank you in advance for your contributions! We really appreciate it. 🙏 diff --git a/docs/contribute/doc-style-guide.md b/docs/contribute/doc-style-guide.md new file mode 100644 index 0000000000..901df0c55c --- /dev/null +++ b/docs/contribute/doc-style-guide.md @@ -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 + + + +| 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: + +```shell +yarn workspace @backstage/plugin- 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. | | diff --git a/microsite/sidebars.ts b/microsite/sidebars.ts index 78319b4cdb..871fbe09e9 100644 --- a/microsite/sidebars.ts +++ b/microsite/sidebars.ts @@ -732,6 +732,7 @@ export default { 'contribute/index', 'contribute/getting-involved', 'contribute/project-structure', + 'contribute/doc-style-guide', ], ), sidebarElementWithIndex(