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(