Search functionality in the context of the provided project (https://github.com/helixml/docs/) can be implemented using search engines like Elasticsearch, which is already being used in Backstage. The search engine can index documentation sites and provide search functionality across all sites or per site.
To improve navigation, the following steps can be taken:
- Well-designed information architecture: Ensure that the documentation is organized in a logical and intuitive manner. This includes having a clear hierarchy of sections, subsections, and pages.
- User-friendly browse experience: Provide a clear and easy-to-use navigation menu that allows users to quickly find the information they need.
- Intelligent suggestions: Use metrics and user behavior to provide suggestions and recommendations to users based on their role and search history.
The following are some examples and best practices for implementing search and navigation:
- Query Translators: Because different search engines have unique and robust query languages, there needs to be a translation layer between an abstract search query and a concrete search query that is specific to a search engine.
- Documents and Indices: Documents are made up of metadata fields, at a minimum including a title, text, and location (as in a URL).
- Content organization: The documentation side-bar menu is built from the current section tree starting below docs/. It will show all sections and their pages. If you don’t want to list a section or page, set the toc_hide flag to true in front matter: toc_hide : true.
- Global navigation: Navigation item text should be as short as possible, be contextual, and avoid jargon or terms of art. Navigation links must follow the rules documented in the data file. The global nav has five levels: Section, Category, Doc, Doc, Doc.
- Discoverability and search: Implement documentation search across all documentation sites and per documentation site using Elasticsearch. Implement a documentation home page in Backstage that surfaces the most important documents and uses metrics to list the company’s most used doc sites.
- Use case variations: Consider different use cases and variations when implementing search and navigation.
Sources:
- https://backstage.io/docs/features/search/concepts
- https://kubernetes.io/docs/contribute/style/content-organization
- https://docs.gitlab.com/ee/development/documentation/site_architecture/global_nav.html
- https://backstage.io/blog/2020/09/08/announcing-tech-docs
- https://developers.redhat.com/learn/openshift-data-science/red-hat-openshift-data-science-documentation-and-resources
- https://backstage.io/docs/features/search/how-to-guides
- https://backstage.io/docs/features/search/getting-started
- https://backstage.io/docs/reference/plugin-search-common
- https://helm.sh/ko/docs/helm/helm_search
- https://code.visualstudio.com/docs/getstarted/settings
- https://grafana.com/docs/writers-toolkit/structure/about-documentation-design
