From e8d9c49159d35a32d9a0fbb51aafd1524db5685d Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Sat, 12 Apr 2025 15:28:28 +0200 Subject: [PATCH 1/2] docs: add a small section to the CONTRIBUTING guide on how to contribute docs, acts as a small intro which can be built on if need be Signed-off-by: Peter Macdonald --- CONTRIBUTING.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bc67fba8c6..105d64e418 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,6 +17,7 @@ If you need help, just jump into our [Discord chatroom](https://discord.gg/backs - [Accessibility](#accessibility) - [Get Started!](#get-started) - [Coding Guidelines](#coding-guidelines) +- [Contributing Docs](#contributing-docs) - [Package Scripts](#package-scripts) - [Local configuration](#local-configuration) - [Creating Changesets](#creating-changesets) @@ -117,6 +118,20 @@ If there are any updates in `markdown` file please make sure to run `yarn run li The Backstage development environment does not require any specific editor, but it is intended to be used with one that has built-in linting and type-checking. The development server does not include any checks by default, but they can be enabled using the `--check` flag. Note that using the flag may consume more system resources and slow things down. +## Contributing Docs + +Contributing to the docs is one of the best ways to start getting involved with Backstage. The documentation site is often the first stop for anyone using or exploring Backstage, so even small improvements can have a big impact! + +To help your changes get reviewed and merged smoothly, please keep the following in mind: + +- Try to group related updates into a single pull request. For example, if you notice missing admonitions or outdated information in a section, feel free to update all of it together. This makes it easier for maintainers to review your contribution in context. + +- 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) + +Thank you in advance for your contributions! We really appreciate it. 🙏 + ## Package Scripts There are many commands to be found in the root [package.json](https://github.com/backstage/backstage/blob/master/package.json), here are some useful ones: From dd6b147454a6b4b6fbe42845a876504291b11d88 Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Mon, 14 Apr 2025 13:31:46 +0200 Subject: [PATCH 2/2] fix: update the headings, add small reference from the contrib section of the docs back to the section in CONTRIBUTING.md Signed-off-by: Peter Macdonald --- CONTRIBUTING.md | 4 ++-- docs/contribute/getting-involved.md | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 105d64e418..6a91fc4196 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ If you need help, just jump into our [Discord chatroom](https://discord.gg/backs - [Accessibility](#accessibility) - [Get Started!](#get-started) - [Coding Guidelines](#coding-guidelines) -- [Contributing Docs](#contributing-docs) +- [Documentation Guidelines](#documentation-guidelines) - [Package Scripts](#package-scripts) - [Local configuration](#local-configuration) - [Creating Changesets](#creating-changesets) @@ -118,7 +118,7 @@ If there are any updates in `markdown` file please make sure to run `yarn run li The Backstage development environment does not require any specific editor, but it is intended to be used with one that has built-in linting and type-checking. The development server does not include any checks by default, but they can be enabled using the `--check` flag. Note that using the flag may consume more system resources and slow things down. -## Contributing Docs +## Documentation Guidelines Contributing to the docs is one of the best ways to start getting involved with Backstage. The documentation site is often the first stop for anyone using or exploring Backstage, so even small improvements can have a big impact! diff --git a/docs/contribute/getting-involved.md b/docs/contribute/getting-involved.md index c11e870752..4b8c4dfc6f 100644 --- a/docs/contribute/getting-involved.md +++ b/docs/contribute/getting-involved.md @@ -43,6 +43,8 @@ submitting them. You'll find the website sources under [/microsite](https://gith with instructions for building and locally serving the website in the [README](/microsite#readme). +For additional information and helpful guidelines on how to contribute to the documentation, check out these [Documentation Guidelines](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md#documentation-guidelines)! + ### Contribute to Storybook We think the best way to ensure different plugins provide a consistent experience is through a solid set of reusable UI/UX components. Backstage uses [Storybook](http://backstage.io/storybook).