You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In order to support versioning in the new docs system, we need to add some built-in admonitions or "directives" that are context-specific and can be applied at the section, paragraph, or line-level.
In the existing doc system, they look like this:
However this is insufficient for features have varied states across multiple contexts. For example something can be GA in one context but tech preview in another.
In the new doc system, we should have a way to accomplish something like this:
You can see an example of how we played with extending the admonitions in the old system to accomplish this in elastic/docs#3121
Similar to the page-level metadata, we think that that admonitions need to communicate the following dimensions:
Deployment type. For example:
Elastic Cloud Hosted
Elastic Cloud Serverless
Elastic Cloud Enterprise
Elastic Cloud Kubernetes
Self-managed (need to confirm the terminology for this Elastic Stack on-prem self-managed context)
discontinued (historically we've immediately removed content when the feature ceases to be supported, but this might not be the case with pages that contain information that spans versions)
unavailable (for content that doesn't exist in a specific context and is never coming or not coming anytime soon)
ga (replaces "added" in the current docs system since it was not entirely clear how/if that overlapped with beta/preview states)
Version
Only required for some admonitions (e.g. deprecated in X.Y.Z, ga in YYYY-MM-DD) and contexts (e.g. not necessary for serverless admonitions until/if we start versioning it)
TIP: As in our current docs system, we think it's a good idea to make those category values derived rather than something every writer has to type out, since terminology for things like ESS/Elastic Cloud/Elastic Cloud Hosted have changed and might change again. However these directives are implemented should also support future additions if we add new dimensions (e.g. new product phases or deployment types).
NOTE: We haven't gotten input from the design team yet on the best possible way to make these admonitions informative but not too disruptive. We will also work on writer guidelines so that we don't end up with misuse or over-use.
The text was updated successfully, but these errors were encountered:
Relates to #49, https://github.com/elastic/docs-builder-example/blob/main/docs/source/markup/admonitions.md
In order to support versioning in the new docs system, we need to add some built-in admonitions or "directives" that are context-specific and can be applied at the section, paragraph, or line-level.
In the existing doc system, they look like this:
However this is insufficient for features have varied states across multiple contexts. For example something can be GA in one context but tech preview in another.
In the new doc system, we should have a way to accomplish something like this:
You can see an example of how we played with extending the admonitions in the old system to accomplish this in elastic/docs#3121
Similar to the page-level metadata, we think that that admonitions need to communicate the following dimensions:
TIP: As in our current docs system, we think it's a good idea to make those category values derived rather than something every writer has to type out, since terminology for things like ESS/Elastic Cloud/Elastic Cloud Hosted have changed and might change again. However these directives are implemented should also support future additions if we add new dimensions (e.g. new product phases or deployment types).
NOTE: We haven't gotten input from the design team yet on the best possible way to make these admonitions informative but not too disruptive. We will also work on writer guidelines so that we don't end up with misuse or over-use.
The text was updated successfully, but these errors were encountered: