opensearch-project
[DOC] [RFC] OpenSearch documentation 2024 strategy and roadmap
Documentation strategy
Hello! Welcome to the proposed OpenSearch documentation strategy for what remains of 2024. Here are the key initiatives that are underway to help the OpenSearch community better understand and use OpenSearch. If you have additional ideas on where we should focus, please comment!
- Close documentation gaps
- Support new development
- Address community feedback
- Implement infrastructure improvements
Close documentation gaps
Our main focus is to close the content gaps in our documentation, and we anticipate that we can close the gaps by end of Q3. We have known gaps in our REST APIs, aggregations, mappings, query DSL, and ingest processors content. If you know of other gaps, please let us know by creating an issue.
Support new development
We will support all new development on OpenSearch Project. The documentation team partners with developers to ensure all features for each new release have complete, accurate, and high quality documentation.
- OpenSearch/OpenSearch Dashboards — In 2024, seven releases for OpenSearch/OpenSearch Dashboards are planned.
- Data Prepper — Data Prepper has 4 releases planned, or one per quarter.
- OpenSearch Benchmark — Benchmark has monthly releases planned for 2024, with only minor updates to the documentation. A major release will be delivered in H2, 2024.
Address community feedback
An ongoing goal of ours is to maintain high quality content in the OpenSearch.org documentation website. This involves regularly collecting, analyzing, and addressing feedback that we receive from our community. We regularly monitor incoming suggestions from the feedback mechanism on the website, requests or conversations in Slack, questions in the community forums and other community engagements, and through GitHub. All incoming issues and PRs are triaged, and we ensure that all contributions follow the OpenSearch quality standards and guidelines.
We try to address feedback as we receive it, but we do have a large backlog. If you have expert knowledge in a particular area, feel free grab one or two suggestions to address. For more information, see Issues labeled = feedback.
Implement infrastructure improvements
Here are some infrastructure improvements we are planning to address in 2024, pending development support.
- Improvements to the search engine on the openseach.org website.
- SEO improvements (Done). We have old content (1.0 - 1.2) still appearing in Google searches. The suggested fix is to add canonical links to the older pages. **Update: This is done as of end of Q2, 2024. If you see any old pages come up in your searches, please let us know.
- Cache invalidation issue. Sometimes links don't always resolve when the website is building. See https://github.com/opensearch-project/documentation-website/issues/5846.
Documentation roadmap
This is the proposed roadmap for 2024. An “x” means we will work on and/or complete the task in the quarter. For the OpenSearch release schedule, see release schedule.
| Goal | Task | 24-Q1 | 24-Q2 | 24-Q3 | 24-Q4 | Status |
|---|---|---|---|---|---|---|
| Content gap | Address missing REST APIs | x | x | In progress | ||
| Content gap | Address missing query DSL | x | x | In progress | ||
| Content gap | Address missing aggregations | x | x | In progress | ||
| Conent gap | Address missing text analysis | x | x | Not started | ||
| Content gap | Address missing mappings | x | x | In progress | ||
| Content gap | Address missing searching data | x | x | In progress | ||
| Feedback | Add getting started in OpenSearch | x | x | Done | ||
| New dev | OpenSearch 2.12 (Feb 6) | x | Done | |||
| New dev | OpenSearch 2.13 (3/19) | x | Done | |||
| New dev | OpenSearch 2.14 ( 4/30) | x | Done | |||
| New dev | OpenSearch 2.15 (6/10) | x | Done | |||
| New dev | OpenSearch 2.16 (7/23) | x | In progress | |||
| New dev | OpenSearch 2.17 (9/3) | x | Not started | |||
| New dev | OpenSearch 2.18 (10/22) | x | Not started | |||
| New dev | Data Prepper 2.7 | x | Done | |||
| New dev | Data Prepper 2.8 | x | Done | |||
| New dev | Data Prepper 2.9 | x | Not started | |||
| New dev | Data Prepper 2.10 | x | Not started | |||
| New dev | OpenSearch Benchmark | x | x | x | x | Ongoing |
| Feedback | Address security feedback; add getting started with security and best practices; security backlog | x | x | x | In progress | |
| Feedback | Address community feedback | x | x | x | x | Ongoing |
| Feedback | Triage incoming issues/PRs | x | x | x | x | Ongoing |
Recent improvements
So far in 2024, the OpenSearch documentation team made keys improvements, including:
Separated the component documentation
OpenSearch Project is comprised of several components, including OpenSearch (the core engine), OpenSearch Dashboards (data visualization), Data Prepper (data ingestion), and OpenSearch Benchmark (performance measurement). Since the documentation content is contained within one pipeline, all of the components appeared as if they fell under the same version. The components are split now. Future updates will include separate pipelines and version selector for each, as needed. See https://opensearch.org/docs/latest/.
Added a Getting Started section
Recent feedback revealed that the community had trouble knowing where to start with their OpenSearch journey, so we’ve added a new getting started section to help users get started. If you have any feedback, please submit feedback in the applicable page.
Improved the documentation-website repo
- Improved automated error checking
- Automated backports on merge
- Automated branch deletion on merge
Additional resources
- Contributing.md - http://contributing.md/
- YouTube video on the documentation process - https://www.youtube.com/watch?v=zmVC3fQwnVI
- Slack channel - https://opensearch.slack.com/archives/C052GAV1MQF
Call to action
Tell us what you think! Are we focused on the right things? Is anything missing? Should something be moved up in prioritization? Thank you for supporting OpenSearch.
Regarding the item:
Improvements to the search engine on the openseach.org website.
I would really welcome if we can filter/restrict the search to specific topic/section only. For example I would like to be able to run searches only on top of OpenSearch server section (excluding Dashboards, Data Prepper, Clients and other sections).
And on top of that I would like to be able to focus searches on specific parts of the section, like the: "API reference only".
Shall I open a ticket in https://github.com/opensearch-project/project-website-search ?
Thanks for your input, @lukas-vlcek! Yes, please enter an issue in the project-website repo. We've had requests from the community to be able to search only the documentation, but not yet for this level of granularity.