elastic / elastic/docs-content
Refine and improve "Reading indices from older Elasticsearch versions" document
- Dominant language
- No language data
- Stars
- 47
- Forks
- 261
- Avg merge
- 3d 12h
- Merged PRs (30d)
- 116
Description
This is a follow up issue of https://github.com/elastic/docs-content/issues/2343
We need to review [this doc](https://www.elastic.co/docs/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions), as how to improve this is not straight forward. We might want to get feedback from PMs here.
Issues:
- We talk about "archive functionality" in that doc, we tell the users that they can rely on that feature to read indices form old Elasticsearch versions, but we don't explain how to use it, and how to make / archive an index for read only. --> The doc needs much better reading flow.
- Title: we need to check if the title is appropriate, it's long, it uses the word `older` when vale linting suggests `earlier`. We should consider archive indices, read-only indices for compatibility, and other options (IMO archive indices won't be clear at all, not even sure why we say archive functionality when it's more a simple read-only access to old-version data structures.)
- Supported backends for this functionality: it's snapshots or real indices, but it's not properly explained... we just have a misleading paragraph that says:
> For this, Elasticsearch can access older snapshot repositories going back to version 5.
That paragraph makes the wrong impression that archive functionality only works through snapshots, while it also works for standard indices stored in the nodes.
- How this document and functionality is linked and mentioned within the upgrade docs: upgrade assistant helps with this, and the user could also do this manually, but the steps are missing.
Action items:
- [ ] Analyze all this and determine:
- [ ] Is there a better title?
- [ ] Should we use archive functionality and archive index terms? (the archive settings are perfectly well explained, but this isn't).
- [ ] Should we improve the introduction from concepts point of view?
- [ ] Add a section with the steps to archive an index (maybe it's marking it only as read-only), explaining that this can be done through a few clicks within the upgrade assistant UI, and with the API (not sure how exactly with the API).
- [ ] Check documents that link to this and consider refining how this is presented.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.