We need better docs!
summary
OpenSearch documentation falls behind because releases land every six weeks and writers lag code changes; current docs are fragmented across blog posts, GitHub issues and old API pages. Suggested fixes: bake URL versioning into doc paths so users and Google land on the right version, add CI checks for link/syntax validity, auto-generate doc drafts from code/comments with AI to reduce writer toil, and replace the docs search with vector/hybrid search backed by an upgraded OpenSearch index.
AI-written summary · about
chapters (10)
- 0:00Documentation problem
- 1:27Current docs challenges
- 2:52Diataxis framework
- 4:36Community feedback gaps
- 6:02GitHub insights for docs
- 7:26Versioning and compatibility
- 8:30AI tools for docs
- 9:34Docs quality tools
- 10:17OpenSearch docs search
- 11:41Testing search engine
related talks
30mDocs For All: Improving Open Source Accessibility
56mEffective Documentation: The Key to Open Source Growth
33mOSS Documentation Workshop
14mdocs docs docs
35mLearning by Example: Highlights from Google Season of Docs
45mDocs or it didn't happen!
35mDocumenting APIs: new era, same craft
30mHow you write matters in open source