Improve clarity and context on the number_of_shards option page #3829
Description
Type of issue
Other
What documentation page is affected
https://www.elastic.co/docs/reference/elasticsearch/curator/option_number_of_shards
What happened?
Description
We’ve received user feedback that includes positive points about clarity and visuals, along with several actionable suggestions for improving usability and completeness.
Feedback summary
What's working:
- Default value display: Clearly showing the default is appreciated and we should keep this consistent.
- Note/Important styling: These stand out well. No change needed.
What could be improved:
- Description placement: The definition of what the property is should appear at the top. It’s currently easy to miss, especially for newer users.
- Parameter clarity: It’s not clear whether this option is mandatory or optional, or what data type it accepts. For numbers it’s inferred, but for other types it should be explicit.
- Assumed knowledge: Add a link to introductory content explaining shards, similar to the approach used in the shrink docs.
- Additional guidance: Add links to related resources on shard sizing and overview to help users understand context, as this is a common source of confusion.
- Deployment relevance: Clarify whether this option applies to Elastic Cloud, on-prem, and/or serverless deployments.
Additional info
No response
Action
added by (@georgewallace)
- Move description up
- Add applies_to tags to content
- Review the additional feedback to determine actions to take
- See what actions can be taken across all the options as they are all similar