diff --git a/docs/faq/index.md b/docs/faq/index.md new file mode 100644 index 0000000000..93e3e90fbe --- /dev/null +++ b/docs/faq/index.md @@ -0,0 +1,15 @@ +--- +id: index +title: Overview +description: FAQ Overview +--- + +This section contains answers to frequently asked questions about Backstage. + +### [Product FAQ](../faq/product.md) + +Questions related to product and design. + +### [Technical FAQ](../faq/technical.md) + +General technical questions about Backstage. diff --git a/docs/faq/product.md b/docs/faq/product.md new file mode 100644 index 0000000000..9d2a32f33e --- /dev/null +++ b/docs/faq/product.md @@ -0,0 +1,66 @@ +--- +id: product +title: Product FAQ +description: Questions related to product and design. +--- + +### Can we call Backstage something different? So that it fits our company better? + +Yes, Backstage is just a platform for building your own developer portal. We +happen to call our internal version Backstage, as well, as a reference to our +music roots. You can call your version whatever suits your team, company, or +brand. + +### Is Backstage a monitoring platform? + +No, but it can be! Backstage is designed to be a developer portal for all your +infrastructure tooling, services, and documentation. So, it's not a monitoring +platform — but that doesn't mean you can't integrate a monitoring tool into +Backstage by writing [a plugin](#what-is-a-plugin-in-backstage). + +### How is Backstage licensed? + +Backstage was released as open source software by Spotify and is licensed under +[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0). + +### Why did we open source Backstage? + +We hope to see Backstage become the infrastructure standard everywhere. When we +saw how much Backstage improved developer experience and productivity +internally, we wanted to share those gains. After all, if Backstage can create +order in an engineering environment as open and diverse as ours, then we're +pretty sure it can create order (and boost productivity) anywhere. To learn +more, read our blog post, +"[What the heck is Backstage anyway?](https://backstage.io/blog/2020/03/18/what-is-backstage)" + +### Will Spotify's internal plugins be open sourced, too? + +Yes, we've already started releasing open source versions of some of the plugins +we use here, and we'll continue to do so. +[Plugins](#what-is-a-plugin-in-backstage) are the building blocks of +functionality in Backstage. We have over 120 plugins inside Spotify — many of +those are specialized for our use, so will remain internal and proprietary to +us. But we estimate that about a third of our existing plugins make good open +source candidates. (And we'll probably end up writing some brand new ones, too.) + +### What's the roadmap for Backstage? + +We envision three phases, which you can learn about in +[our project roadmap](../overview/roadmap.md). Even though the open source version +of Backstage is relatively new compared to our internal version, we have already +begun work on various aspects of all three phases. Looking at the +[milestones for active issues](https://github.com/backstage/backstage/milestones) +will also give you a sense of our progress. + +### My company doesn't have thousands of developers or services. Is using Backstage excessive for our needs? + +Not at all! A core reason to adopt Backstage is to standardize how software is +built at your company. It's easier to decide on those standards as a small +company, and grows in importance as the company grows. Backstage sets a +foundation, and an early investment in your infrastructure becomes even more +valuable as you grow. + +### Our company has a strong design language system/brand that we want to incorporate. Does Backstage support this? + +Yes! The Backstage UI is built using Material UI. With the theming capabilities +of Material UI, you are able to adapt the interface to your brand guidelines. diff --git a/docs/FAQ.md b/docs/faq/technical.md similarity index 74% rename from docs/FAQ.md rename to docs/faq/technical.md index 7b935140e6..55bb1af615 100644 --- a/docs/FAQ.md +++ b/docs/faq/technical.md @@ -1,74 +1,9 @@ --- -id: FAQ -title: FAQ -description: All FAQ related to Backstage +id: technical +title: Technical FAQ +description: General technical questions about Backstage. --- -## Product FAQ - -### Can we call Backstage something different? So that it fits our company better? - -Yes, Backstage is just a platform for building your own developer portal. We -happen to call our internal version Backstage, as well, as a reference to our -music roots. You can call your version whatever suits your team, company, or -brand. - -### Is Backstage a monitoring platform? - -No, but it can be! Backstage is designed to be a developer portal for all your -infrastructure tooling, services, and documentation. So, it's not a monitoring -platform — but that doesn't mean you can't integrate a monitoring tool into -Backstage by writing [a plugin](#what-is-a-plugin-in-backstage). - -### How is Backstage licensed? - -Backstage was released as open source software by Spotify and is licensed under -[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0). - -### Why did we open source Backstage? - -We hope to see Backstage become the infrastructure standard everywhere. When we -saw how much Backstage improved developer experience and productivity -internally, we wanted to share those gains. After all, if Backstage can create -order in an engineering environment as open and diverse as ours, then we're -pretty sure it can create order (and boost productivity) anywhere. To learn -more, read our blog post, -"[What the heck is Backstage anyway?](https://backstage.io/blog/2020/03/18/what-is-backstage)" - -### Will Spotify's internal plugins be open sourced, too? - -Yes, we've already started releasing open source versions of some of the plugins -we use here, and we'll continue to do so. -[Plugins](#what-is-a-plugin-in-backstage) are the building blocks of -functionality in Backstage. We have over 120 plugins inside Spotify — many of -those are specialized for our use, so will remain internal and proprietary to -us. But we estimate that about a third of our existing plugins make good open -source candidates. (And we'll probably end up writing some brand new ones, too.) - -### What's the roadmap for Backstage? - -We envision three phases, which you can learn about in -[our project roadmap](overview/roadmap.md). Even though the open source version -of Backstage is relatively new compared to our internal version, we have already -begun work on various aspects of all three phases. Looking at the -[milestones for active issues](https://github.com/backstage/backstage/milestones) -will also give you a sense of our progress. - -### My company doesn't have thousands of developers or services. Is using Backstage excessive for our needs? - -Not at all! A core reason to adopt Backstage is to standardize how software is -built at your company. It's easier to decide on those standards as a small -company, and grows in importance as the company grows. Backstage sets a -foundation, and an early investment in your infrastructure becomes even more -valuable as you grow. - -### Our company has a strong design language system/brand that we want to incorporate. Does Backstage support this? - -Yes! The Backstage UI is built using Material UI. With the theming capabilities -of Material UI, you are able to adapt the interface to your brand guidelines. - -## Technical FAQ - ### What technology does Backstage use? Backstage is a large scale [TypeScript](https://www.typescriptlang.org/) @@ -116,7 +51,7 @@ type of content. Plugins all use a common set of platform APIs and reusable UI components. Plugins can fetch data either from the backend or an API exposed through the proxy. -Learn more about [the different components](overview/what-is-backstage.md) that +Learn more about [the different components](../overview/what-is-backstage.md) that make up Backstage. ### Why can't I dynamically install plugins without modifications to the app? @@ -253,7 +188,7 @@ data is shared with. Yes. The core frontend framework could be used for building any large-scale web application where (1) multiple teams are building separate parts of the app, and (2) you want the overall experience to be consistent. That being said, in -[Phase 2](overview/roadmap.md) of the project we will add features that are +[Phase 2](../overview/roadmap.md) of the project we will add features that are needed for developer portals and systems for managing software ecosystems. Our ambition will be to keep Backstage modular. diff --git a/docs/overview/support.md b/docs/overview/support.md index c968405a99..38bb60784f 100644 --- a/docs/overview/support.md +++ b/docs/overview/support.md @@ -11,7 +11,7 @@ description: Support and Community Details and Links here if you want to contribute. - [RFCs](https://github.com/backstage/backstage/labels/rfc) - Help shape the technical direction by reviewing _Request for Comments_ issues. -- [FAQ](../FAQ.md) - Frequently Asked Questions. +- [FAQ](../faq/index.md) - Frequently Asked Questions. - [Code of Conduct](https://github.com/backstage/backstage/blob/master/CODE_OF_CONDUCT.md) - This is how we roll. - [Blog](https://backstage.io/blog/) - Announcements and updates. diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 187c41ad75..e32e027807 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -478,7 +478,7 @@ "architecture-decisions/adrs-adr012", "architecture-decisions/adrs-adr013" ], - "FAQ": ["FAQ"], + "FAQ": ["faq/index", "faq/product", "faq/technical"], "Accessibility": ["accessibility/index"] } } diff --git a/mkdocs.yml b/mkdocs.yml index bf4024759b..8c9f84ba81 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -214,4 +214,7 @@ nav: - ADR011 - Plugin Package Structure: 'architecture-decisions/adr011-plugin-package-structure.md' - ADR012 - Plugin Package Structure: 'architecture-decisions/adr012-use-luxon-locale-and-date-presets.md' - ADR013 - Plugin Package Structure: 'architecture-decisions/adr013-use-node-fetch.md' - - FAQ: FAQ.md + - FAQ: + - Overview: 'faq/index.md' + - Product FAQ: 'faq/product.md' + - Technical FAQ: 'faq/technical.md'