Incorrect applies tags (not too bad!)

[shainaraskas]

Type of issue

Inaccurate

What documentation page is affected

from a spot check, we know the following topics are affected (misapplied serverless tags spotted)

• watcher (fixed here)
• ilm (fixed? fix 1 fix 2 fix 3)
• ccs

and we suspect there are more

Action

• building off of [Issue]: ILM is mistakenly labeled as a serverless feature #1196 and [Issue]: stray hosted tags left in docs #1197, we need to audit our applies tags to make sure the right ones are on the right docs
• As a first step, we can go through the list of features that are not available on Serverless and spot check the related documentation to remove the Serverless tags from them so that we have consistency

consider ideas for guardrails to help with this process and raise with eng / the rest of the docs team

[shainaraskas]

misapplied serverless tags spotted:

• watcher
• ilm
• ccs
  +++

[georgewallace]

Adding to this issue my thoughts. Determining intent for our pages can be a bit of a challenge when we have pages that talk about multiple topics.

Do we need more front matter to help identify content... i.e. do we have a topics or some other tag that can have an array of topics touches in the article. For example, ILM, data streams, etc. to help us easily identify content across our docs? If we identified that an article talks about ILM we would inherently know that it should not pertain to serverless, unless it was about index lifecycle all up and included data streams. If it did though, then it would still warrant that the content on that page either be identified as pertaining to stack or serverless depending on what topic we are talking about. This may take us to the idea that the content should be split up. Do we have a list of core topics that may exist?

I also think this means that we need to define some core requirements for what is required on each page. For instance, stack and serverless are top level elements per the Structured model in our syntax guide. This leads me to believe that all content must have at least one of these elements as an applies_to tag on the page. If we agree to this case then we should add this to our build checks to ensure that when a PR is created it checks to ensure at least one of these tags are present. This could be a warning until we have the content in a good place. But this will at least ensure we have these key things defined.

Bringing them together. If we have a page that only has serverless and also has the topic of ILM, this would be a incorrect combination and therefore we should call that out during build, or even with a linter if we didn't want to be as strict. This would require us though to have some kind of mapping defined somewhere of the mappings that are not acceptable.

[shainaraskas]

This leads me to believe that all content must have at least one of these elements as an applies_to tag on the page. If we agree to this case then we should add this to our build checks to ensure that when a PR is created it checks to ensure at least one of these tags are present. This could be a warning until we have the content in a good place. But this will at least ensure we have these key things defined.

I don't think this assumption is correct. the stack/serverless case is used when functionality is at the stack component level, but we have lots of things implemented at the deployment level, or at both the deployment + stack component level, where the choices would be self-managed/ece/ech/eck/serverless.

[shainaraskas]

also see #1180

[georgewallace]

I don't think this assumption is correct. the stack/serverless case is used when functionality is at the stack component level, but we have lots of things implemented at the deployment level, or at both the deployment + stack component level, where the choices would be self-managed/ece/ech/eck/serverless.

If this is the case as it sounds it is, then if stack/serverless doesn't apply to that page then for consistency I would expect it to have a deployment applies_to or something else.

[ppf2]

As a stop gap, we may want to go through the list of features that are not available on Serverless and spot check the related documentation to remove the Serverless tags from them so that we have consistency. Thx!