From 25e6212fedcffef69e0873480ac1470b3e456402 Mon Sep 17 00:00:00 2001 From: npiyush97 Date: Wed, 10 Jan 2024 14:41:47 +0530 Subject: [PATCH 01/11] new faq draft Signed-off-by: npiyush97 --- docs/faq/FAQ.md | 19 +++++++++ docs/faq/adoption.md | 7 +++ docs/faq/corefeatures.md | 7 +++ docs/faq/deployment.md | 7 +++ docs/faq/framework.md | 7 +++ docs/faq/product-faq.md | 68 +++++++++++++++++++++++++++++ docs/{FAQ.md => faq/technical.md} | 71 ++----------------------------- microsite/sidebars.json | 10 ++++- 8 files changed, 128 insertions(+), 68 deletions(-) create mode 100644 docs/faq/FAQ.md create mode 100644 docs/faq/adoption.md create mode 100644 docs/faq/corefeatures.md create mode 100644 docs/faq/deployment.md create mode 100644 docs/faq/framework.md create mode 100644 docs/faq/product-faq.md rename docs/{FAQ.md => faq/technical.md} (75%) diff --git a/docs/faq/FAQ.md b/docs/faq/FAQ.md new file mode 100644 index 0000000000..4b50a38818 --- /dev/null +++ b/docs/faq/FAQ.md @@ -0,0 +1,19 @@ +--- +id: FAQ +title: FAQ +description: All FAQ related to Questions +--- + +## FAQS + +[Product FAQS](../faq/product-faq.md) + +[Technical FAQS](../faq/technical.md) + +[Adoption FAQS](../faq/adoption.md) + +[Deployment FAQS](../faq/deployment.md) + +[Framework FAQS](../faq/framework.md) + +[Core features FAQS](../faq/corefeatures.md) diff --git a/docs/faq/adoption.md b/docs/faq/adoption.md new file mode 100644 index 0000000000..0939fef069 --- /dev/null +++ b/docs/faq/adoption.md @@ -0,0 +1,7 @@ +--- +id: Adoption FAQs +title: Adoption FAQs +description: All FAQs related to Adoption +--- + +## ADOPTION FAQ diff --git a/docs/faq/corefeatures.md b/docs/faq/corefeatures.md new file mode 100644 index 0000000000..8a46929797 --- /dev/null +++ b/docs/faq/corefeatures.md @@ -0,0 +1,7 @@ +--- +id: CORE FEATURES FAQs +title: Core Features FAQs +description: All FAQs related to Core Features +--- + +## Core Features FAQs diff --git a/docs/faq/deployment.md b/docs/faq/deployment.md new file mode 100644 index 0000000000..a67586bc2a --- /dev/null +++ b/docs/faq/deployment.md @@ -0,0 +1,7 @@ +--- +id: DEPLOYMENT FAQs +title: Deployment FAQs +description: All FAQs related to DEPLOYMENT +--- + +## Deployment FAQs diff --git a/docs/faq/framework.md b/docs/faq/framework.md new file mode 100644 index 0000000000..409a273bfb --- /dev/null +++ b/docs/faq/framework.md @@ -0,0 +1,7 @@ +--- +id: FRAMEWORK FAQs +title: Framework FAQs +description: All FAQ related to FRAMEWORK +--- + +## FRAMEWORK FAQs diff --git a/docs/faq/product-faq.md b/docs/faq/product-faq.md new file mode 100644 index 0000000000..68d8918ad0 --- /dev/null +++ b/docs/faq/product-faq.md @@ -0,0 +1,68 @@ +--- +id: Product FAQs +title: Product FAQs +description: All FAQs related to Product +--- + +## Product FAQs + +### 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 75% rename from docs/FAQ.md rename to docs/faq/technical.md index 7b935140e6..a79c673799 100644 --- a/docs/FAQ.md +++ b/docs/faq/technical.md @@ -1,73 +1,10 @@ --- -id: FAQ -title: FAQ -description: All FAQ related to Backstage +id: Technical FAQs +title: Technical FAQs +description: All FAQs related to Technical --- -## 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 +## Technical FAQs ### What technology does Backstage use? diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 5dd5ce93f8..81bd0daec0 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -472,7 +472,15 @@ "architecture-decisions/adrs-adr012", "architecture-decisions/adrs-adr013" ], - "FAQ": ["FAQ"], + "FAQ": [ + "faq/FAQ", + "faq/Product FAQs", + "faq/Technical FAQs", + "faq/Adoption FAQs", + "faq/DEPLOYMENT FAQs", + "faq/FRAMEWORK FAQs", + "faq/CORE FEATURES FAQs" + ], "Accessibility": ["accessibility/index"] } } From 103143d3df95671f243231e50cd6492a8641cab5 Mon Sep 17 00:00:00 2001 From: npiyush97 Date: Sat, 20 Jan 2024 22:13:56 +0530 Subject: [PATCH 02/11] added suggested changes Signed-off-by: npiyush97 --- microsite/sidebars.json | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 81bd0daec0..68628f1490 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -473,13 +473,8 @@ "architecture-decisions/adrs-adr013" ], "FAQ": [ - "faq/FAQ", "faq/Product FAQs", - "faq/Technical FAQs", - "faq/Adoption FAQs", - "faq/DEPLOYMENT FAQs", - "faq/FRAMEWORK FAQs", - "faq/CORE FEATURES FAQs" + "faq/Technical FAQs" ], "Accessibility": ["accessibility/index"] } From d004e65f54dc6f9c08c361088f1994f070d9a844 Mon Sep 17 00:00:00 2001 From: npiyush97 Date: Sat, 20 Jan 2024 22:16:56 +0530 Subject: [PATCH 03/11] added suggested changes Signed-off-by: npiyush97 --- microsite/sidebars.json | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 68628f1490..8272f5edfb 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -472,10 +472,7 @@ "architecture-decisions/adrs-adr012", "architecture-decisions/adrs-adr013" ], - "FAQ": [ - "faq/Product FAQs", - "faq/Technical FAQs" - ], + "FAQ": ["faq/Product FAQs", "faq/Technical FAQs"], "Accessibility": ["accessibility/index"] } } From 5a8b6ccda3d14ed8a08e9ef3595fb4fcacd0a6e2 Mon Sep 17 00:00:00 2001 From: npiyush97 Date: Sat, 20 Jan 2024 22:24:29 +0530 Subject: [PATCH 04/11] removed files Signed-off-by: npiyush97 --- docs/faq/FAQ.md | 19 ------------------- docs/faq/adoption.md | 7 ------- docs/faq/corefeatures.md | 7 ------- docs/faq/framework.md | 7 ------- 4 files changed, 40 deletions(-) delete mode 100644 docs/faq/FAQ.md delete mode 100644 docs/faq/adoption.md delete mode 100644 docs/faq/corefeatures.md delete mode 100644 docs/faq/framework.md diff --git a/docs/faq/FAQ.md b/docs/faq/FAQ.md deleted file mode 100644 index 4b50a38818..0000000000 --- a/docs/faq/FAQ.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -id: FAQ -title: FAQ -description: All FAQ related to Questions ---- - -## FAQS - -[Product FAQS](../faq/product-faq.md) - -[Technical FAQS](../faq/technical.md) - -[Adoption FAQS](../faq/adoption.md) - -[Deployment FAQS](../faq/deployment.md) - -[Framework FAQS](../faq/framework.md) - -[Core features FAQS](../faq/corefeatures.md) diff --git a/docs/faq/adoption.md b/docs/faq/adoption.md deleted file mode 100644 index 0939fef069..0000000000 --- a/docs/faq/adoption.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: Adoption FAQs -title: Adoption FAQs -description: All FAQs related to Adoption ---- - -## ADOPTION FAQ diff --git a/docs/faq/corefeatures.md b/docs/faq/corefeatures.md deleted file mode 100644 index 8a46929797..0000000000 --- a/docs/faq/corefeatures.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: CORE FEATURES FAQs -title: Core Features FAQs -description: All FAQs related to Core Features ---- - -## Core Features FAQs diff --git a/docs/faq/framework.md b/docs/faq/framework.md deleted file mode 100644 index 409a273bfb..0000000000 --- a/docs/faq/framework.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: FRAMEWORK FAQs -title: Framework FAQs -description: All FAQ related to FRAMEWORK ---- - -## FRAMEWORK FAQs From 58a83daffcc07b4e6085dd2643f21e963354d570 Mon Sep 17 00:00:00 2001 From: npiyush97 Date: Sat, 20 Jan 2024 22:26:46 +0530 Subject: [PATCH 05/11] fix Signed-off-by: npiyush97 --- docs/faq/deployment.md | 7 ------- 1 file changed, 7 deletions(-) delete mode 100644 docs/faq/deployment.md diff --git a/docs/faq/deployment.md b/docs/faq/deployment.md deleted file mode 100644 index a67586bc2a..0000000000 --- a/docs/faq/deployment.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: DEPLOYMENT FAQs -title: Deployment FAQs -description: All FAQs related to DEPLOYMENT ---- - -## Deployment FAQs From 7ad5b8146e7d8b06ec4c3be1d383f2b425152c24 Mon Sep 17 00:00:00 2001 From: npiyush97 Date: Sat, 20 Jan 2024 22:35:50 +0530 Subject: [PATCH 06/11] added suggested fix Signed-off-by: npiyush97 --- docs/faq/product-faq.md | 2 -- docs/faq/technical.md | 2 -- 2 files changed, 4 deletions(-) diff --git a/docs/faq/product-faq.md b/docs/faq/product-faq.md index 68d8918ad0..29cd22992b 100644 --- a/docs/faq/product-faq.md +++ b/docs/faq/product-faq.md @@ -4,8 +4,6 @@ title: Product FAQs description: All FAQs related to Product --- -## Product FAQs - ### 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 diff --git a/docs/faq/technical.md b/docs/faq/technical.md index a79c673799..1573c14c59 100644 --- a/docs/faq/technical.md +++ b/docs/faq/technical.md @@ -4,8 +4,6 @@ title: Technical FAQs description: All FAQs related to Technical --- -## Technical FAQs - ### What technology does Backstage use? Backstage is a large scale [TypeScript](https://www.typescriptlang.org/) From aede0b73b00696a88a7d726d54741b7c46cf24a1 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 21 Jan 2024 14:38:02 +0100 Subject: [PATCH 07/11] docs/faq: add back index + frontmatter tweaks Signed-off-by: Patrik Oldsberg --- docs/faq/index.md | 15 +++++++++++++++ docs/faq/{product-faq.md => product.md} | 6 +++--- docs/faq/technical.md | 6 +++--- microsite/sidebars.json | 2 +- 4 files changed, 22 insertions(+), 7 deletions(-) create mode 100644 docs/faq/index.md rename docs/faq/{product-faq.md => product.md} (97%) 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-faq.md b/docs/faq/product.md similarity index 97% rename from docs/faq/product-faq.md rename to docs/faq/product.md index 29cd22992b..6d97206907 100644 --- a/docs/faq/product-faq.md +++ b/docs/faq/product.md @@ -1,7 +1,7 @@ --- -id: Product FAQs -title: Product FAQs -description: All FAQs related to Product +id: product +title: Product FAQ +description: Product FAQ --- ### Can we call Backstage something different? So that it fits our company better? diff --git a/docs/faq/technical.md b/docs/faq/technical.md index 1573c14c59..140b4c0893 100644 --- a/docs/faq/technical.md +++ b/docs/faq/technical.md @@ -1,7 +1,7 @@ --- -id: Technical FAQs -title: Technical FAQs -description: All FAQs related to Technical +id: technical +title: Technical FAQ +description: Technical FAQ --- ### What technology does Backstage use? diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 8272f5edfb..f0f924411b 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -472,7 +472,7 @@ "architecture-decisions/adrs-adr012", "architecture-decisions/adrs-adr013" ], - "FAQ": ["faq/Product FAQs", "faq/Technical FAQs"], + "FAQ": ["faq/index", "faq/product", "faq/technical"], "Accessibility": ["accessibility/index"] } } From f2c5d430d4bc26bb087353931fb2c85e5e76efba Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 21 Jan 2024 14:39:51 +0100 Subject: [PATCH 08/11] docs/faq: update descriptions Signed-off-by: Patrik Oldsberg --- docs/faq/product.md | 2 +- docs/faq/technical.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/faq/product.md b/docs/faq/product.md index 6d97206907..30793ba045 100644 --- a/docs/faq/product.md +++ b/docs/faq/product.md @@ -1,7 +1,7 @@ --- id: product title: Product FAQ -description: Product FAQ +description: Questions related to product and design. --- ### Can we call Backstage something different? So that it fits our company better? diff --git a/docs/faq/technical.md b/docs/faq/technical.md index 140b4c0893..040317b998 100644 --- a/docs/faq/technical.md +++ b/docs/faq/technical.md @@ -1,7 +1,7 @@ --- id: technical title: Technical FAQ -description: Technical FAQ +description: General technical questions about Backstage. --- ### What technology does Backstage use? From d84a93b4a34c9ebd42b6acee08d1522535e33d94 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 21 Jan 2024 14:40:57 +0100 Subject: [PATCH 09/11] docs/overview: update link to FAQ Signed-off-by: Patrik Oldsberg --- docs/overview/support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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. From 636f43b76e17c955aaf55a0be30d0e8e25919ef1 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 21 Jan 2024 15:01:35 +0100 Subject: [PATCH 10/11] docs/faq: update relative links Signed-off-by: Patrik Oldsberg --- docs/faq/product.md | 2 +- docs/faq/technical.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/faq/product.md b/docs/faq/product.md index 30793ba045..9d2a32f33e 100644 --- a/docs/faq/product.md +++ b/docs/faq/product.md @@ -46,7 +46,7 @@ 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 +[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) diff --git a/docs/faq/technical.md b/docs/faq/technical.md index 040317b998..55bb1af615 100644 --- a/docs/faq/technical.md +++ b/docs/faq/technical.md @@ -51,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? @@ -188,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. From 69d52450b8c7d9115ac6a3e92408ee372502e84a Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sun, 21 Jan 2024 16:45:00 +0100 Subject: [PATCH 11/11] mkdocs.yml: update FAQ Signed-off-by: Patrik Oldsberg --- mkdocs.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) 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'