From 9a75db568a9c82ec048353e148602f625aa7a0c6 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Thu, 30 Jun 2022 15:10:00 +0200 Subject: [PATCH] update docs Signed-off-by: Emma Indal --- docs/features/search/README.md | 96 ++++++++++------------------ docs/features/search/architecture.md | 16 +++-- 2 files changed, 45 insertions(+), 67 deletions(-) diff --git a/docs/features/search/README.md b/docs/features/search/README.md index f1744d4d80..69b5987d44 100644 --- a/docs/features/search/README.md +++ b/docs/features/search/README.md @@ -14,60 +14,16 @@ Backstage Search lets you find the right information you are looking for in the ## Features -- A federated, faceted search, searching across all entities registered in your Backstage instance. +- A search that lets you bring your own search engine. +- A search that lets you extend it by creating collators for easily indexing content from plugins and other sources. +- A search that lets you create composable search page experiences. +- A search that lets you customize the look and feel of each search result. -- A search that lets you plug in your own search engine of choice. - -- A standardized search API where you can choose to index data from other plugins. - -## Project roadmap - -### Now - -**Backstage Search 1.0** - -A stable Search API for plugin developers to add search to their plugins, and app integrators to expose that to their users. - -We will consider Backstage Search to be 1.0 when the above -use-cases are met, and an ecosystem of search-enabled plugins are available and -stable. - -- As a plugin developer, there should be at least one example of a Backstage - plugin that integrates with search that I can use as inspiration for my own - plugin's search capabilities (for example, the TechDocs plugin). -- As an app integrator, there should be plenty of examples and documentation on - how to customize and extend search in my Backstage instance to meet my - organization's needs. - -### Next - -_Not specified_ - -### Someday/Maybe - -_Not specified_ - -### Done - -See [Done](#done) below for a list of completed roadmap items. +See the more detailed [architecture](./architecture.md) and [tech stack](./architecture.md#tech-stack). ## Supported -The following sections show the search engines and plugins currently supported by Backstage Search. - -### Search engines - -See [Backstage Search Architecture](architecture.md) to get an overview of how -the search engines are used. - -| Search Engines | Support Status | -| -------------------------------------------------- | -------------- | -| [Lunr](./search-engines.md#lunr) | ✅ | -| [ElasticSearch](./search-engines.md#elasticsearch) | ✅ | -| [Postgres](./search-engines.md#postgres) | ✅ | - -[Reach out to us](#get-involved) if you want to chat about support for more -search engines. +The following sections show the plugins and search engines currently supported by Backstage Search. ### Plugins integrated with Backstage Search @@ -77,20 +33,19 @@ search engines. | [TechDocs](./how-to-guides.md#how-to-index-techdocs-documents) | ✅ | | [Stack Overflow](https://github.com/backstage/backstage/blob/master/plugins/stack-overflow-backend/README.md#index-stack-overflow-questions-to-search) | ✅ | -[Reach out to us](#get-involved) if you want to chat about support for more -plugins integrated to search. +### Search engines -## Tech Stack +See [Backstage Search Architecture](architecture.md) to get an overview of how +the search engines are used. -| Stack | Location | -| ------------------------- | ----------------------------------------------------- | -| Frontend Plugin | @backstage/plugin-search | -| Frontend Plugin Library | @backstage/plugin-search-react | -| Isomorphic Plugin Library | @backstage/plugin-search-common | -| Backend Plugin | @backstage/plugin-search-backend | -| Backend Plugin Library | @backstage/plugin-search-backend-node | -| Backend Plugin Module | @backstage/plugin-search-backend-module-elasticsearch | -| Backend Plugin Module | @backstage/plugin-search-backend-module-pg | +| Search Engines | Support Status | +| -------------------------------------------------- | -------------- | +| [ElasticSearch](./search-engines.md#elasticsearch) | ✅ | +| [Lunr](./search-engines.md#lunr) | ✅ | +| [Postgres](./search-engines.md#postgres) | Community ✅ | + +[Reach out to us](#get-involved) if you want to chat about support for more plugin integrations and +search engines. ## Get involved @@ -98,7 +53,7 @@ For any questions, feedback, or to help move search forward, reach out to us in the **#search** channel of our [Discord chatroom](https://github.com/backstage/backstage#community). -## Done +## Use Cases supported **Backstage Search Pre-Alpha** @@ -151,3 +106,18 @@ are met, and can be deployed using a production-ready search engine. - As an integrator, I should be able to tune the queries sent to my chosen search engine according to my organization's needs, but a sensible default query should be in place so that I am not required to do so. + +**Backstage Search 1.0** + +A stable Search API for plugin developers to add search to their plugins, and app integrators to expose that to their users. + +We will consider Backstage Search to be 1.0 when the above +use-cases are met, and an ecosystem of search-enabled plugins are available and +stable. + +- As a plugin developer, there should be at least one example of a Backstage + plugin that integrates with search that I can use as inspiration for my own + plugin's search capabilities (for example, the TechDocs plugin). +- As an app integrator, there should be plenty of examples and documentation on + how to customize and extend search in my Backstage instance to meet my + organization's needs. diff --git a/docs/features/search/architecture.md b/docs/features/search/architecture.md index 4fac0e7cff..f1183cec5f 100644 --- a/docs/features/search/architecture.md +++ b/docs/features/search/architecture.md @@ -4,10 +4,6 @@ title: Search Architecture description: Documentation on Search Architecture --- -> _This architecture has not been fully implemented yet. Find our milestones to -> follow our progress and help contribute on the -> [Search Roadmap](./README.md#project-roadmap)._ - Below you can explore the Search Architecture. Our aim with this architecture is to support a wide variety of search engines, while providing a simple developer experience for plugin developers, and a good out-of-the-box experience for @@ -44,3 +40,15 @@ Architecture non-goals: - At this time, we do not intend to directly support event-driven or incremental index management. Instead, we'll be focused on scheduled, bulk index management. + +## Tech Stack + +| Stack | Location | +| ------------------------- | ----------------------------------------------------- | +| Frontend Plugin | @backstage/plugin-search | +| Frontend Plugin Library | @backstage/plugin-search-react | +| Isomorphic Plugin Library | @backstage/plugin-search-common | +| Backend Plugin | @backstage/plugin-search-backend | +| Backend Plugin Library | @backstage/plugin-search-backend-node | +| Backend Plugin Module | @backstage/plugin-search-backend-module-elasticsearch | +| Backend Plugin Module | @backstage/plugin-search-backend-module-pg |