Standardize our configuration parameter docs to indicate ECE/Elasticsearch Service vs. on-prem support

Open
#139 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Needs clarification
Activity status
Stale
Tech stack
elasticsearch
Domain
documentation

Research direction

Start by reviewing the existing cloud, Elasticsearch, and Kibana configuration-parameter documentation and the linked proposal. Define a consistent way for each parameter to indicate on-premises, ECE, or Elasticsearch Service support. Done means customers reaching a parameter from any of these documentation entry points can identify its supported deployment types.

Written by the indexing model from the issue text.

Description

discussion meta

From @jakommo:

I’ve seen many issues where ECE customers tried to apply on-prem configs, because this was the first search result that came up on google. I was wondering if it would make sense to have both (ECE and on-prem) instructions on the same page, or at least add a note to on-prem docs with a link to the ECE config for this feature.

We probably don't want to merge these docs as they are today, but we should track the issue of how we can improve the documentation of configuration parameters to indicate what they apply to, regardless of your entry point into the docs.

Among the issues that end up confusing customers today:

  • We whitelist parameters for Elasticsearch Service and blacklist parameters for ECE. These are documented only in our cloud docs, but not, say, in our ES or Kibana docs. If you start in our cloud docs, you'll be mostly fine, although we don't document the blacklisted parameters exhaustively today. These docs to link to the ES or Kibana docs.
  • People googling for content can easily end up on the ES or Kibana docs looking at a configuration parameter, with no indication that the parameter is not supported for our cloud products. They try it and

One proposal might be to standardize how we document configuration parameters and add a field that indicates whether or not the parameter is supported on-prem, in ECE, or on the Elasticsearch Service.

Source: https://docs.google.com/document/d/1iUZGa1K-wM5Fu4_Ho3Wep5MQyG-d47XJWve2oGcRyak/edit#bookmark=id.2f62wskyv2rk

Dominant language
Java
Stars
105
Forks
249
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from elastic/stack-docs

All issues in elastic/stack-docs

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.