Define and disambiguate Elasticsearch in glossary #4031
Conversation
Vale Linting ResultsSummary: 1 suggestion found 💡 Suggestions (1)
|
🔍 Preview links for changed docs |
| The term "{{es}}" has several meanings depending on the context in which it is used. | ||
|
|
||
| **The standalone software** | ||
| - The [`elasticsearch` open source project](https://github.com/elastic/elasticsearch) is a standalone piece of software. Pre-built artifacts are available for download and installation from [elastic.co](https://www.elastic.co/downloads/elasticsearch), or you can build from source. Learn more about [deploying a self-managed cluster](/deploy-manage/deploy/self-managed.md). |
There was a problem hiding this comment.
Is project intentional here?
| - The [`elasticsearch` open source project](https://github.com/elastic/elasticsearch) is a standalone piece of software. Pre-built artifacts are available for download and installation from [elastic.co](https://www.elastic.co/downloads/elasticsearch), or you can build from source. Learn more about [deploying a self-managed cluster](/deploy-manage/deploy/self-managed.md). | |
| - The [`elasticsearch` open source product](https://github.com/elastic/elasticsearch) is a standalone piece of software. Pre-built artifacts are available for download and installation from [elastic.co](https://www.elastic.co/downloads/elasticsearch), or you can build from source. Learn more about [deploying a self-managed cluster](/deploy-manage/deploy/self-managed.md). |
There was a problem hiding this comment.
it was intentional, but maybe we don't need to mention either project or product here
There was a problem hiding this comment.
is it important that we hint about methods of installation at this stage? for our own disambiguation needs, I think we need to get across that it is:
- an analytics engine/data store/vector DB
- an installable piece of software
- a component of our platform / the elastic stack
|
|
||
| <br> | ||
| **The platform** | ||
| - The {{es}} [platform](https://www.elastic.co/platform) (also known as the Elastic platform or Search AI Platform) refers to various {{stack}} components deployed together with additional management affordances to power Elastic's managed services. |
There was a problem hiding this comment.
IMO this is the piece that still needs refinement since it's not clear on that site how the "platform" concept overlaps with the Stack or the deployment types.
| - The {{es}} [platform](https://www.elastic.co/platform) (also known as the Elastic platform or Search AI Platform) refers to various {{stack}} components deployed together with additional management affordances to power Elastic's managed services. | |
| - The {{es}} [platform](https://www.elastic.co/platform) (also known as the Elastic platform or Search AI Platform) refers to various {{stack}} components deployed together with additional management affordances to power Elastic's managed services. |
There was a problem hiding this comment.
yeah we shouldn't link there, this is all mainly food for thought, but perhaps if we define "platform" satisfactorily in the glossary too, we can just link to that definition here and reuse it when we revisit the fundamentals or wherever we explain the platform more thoroughly
shainaraskas
left a comment
shainaraskas
left a comment
There was a problem hiding this comment.
i like this direction but added some picky comments because it is my hobby
what this hints to me is that us pivoting from elasticsearch to search for the use case docs is even more important
| The term "{{es}}" has several meanings depending on the context in which it is used. | ||
|
|
||
| **The standalone software** | ||
| - The [`elasticsearch` open source project](https://github.com/elastic/elasticsearch) is a standalone piece of software. Pre-built artifacts are available for download and installation from [elastic.co](https://www.elastic.co/downloads/elasticsearch), or you can build from source. Learn more about [deploying a self-managed cluster](/deploy-manage/deploy/self-managed.md). |
There was a problem hiding this comment.
is it important that we hint about methods of installation at this stage? for our own disambiguation needs, I think we need to get across that it is:
- an analytics engine/data store/vector DB
- an installable piece of software
- a component of our platform / the elastic stack
|
|
||
| **The standalone software** | ||
| - The [`elasticsearch` open source project](https://github.com/elastic/elasticsearch) is a standalone piece of software. Pre-built artifacts are available for download and installation from [elastic.co](https://www.elastic.co/downloads/elasticsearch), or you can build from source. Learn more about [deploying a self-managed cluster](/deploy-manage/deploy/self-managed.md). | ||
| - An `elasticsearch` [node](#glossary-node) is a running instance of the software, which can be part of a [cluster](#glossary-cluster) and exposes REST API endpoints. Refer to the [reference documentation](elasticsearch://reference/elasticsearch/index.md) for usage details. |
There was a problem hiding this comment.
I don't think we refer to nodes as "elasticsearch". we're more likely to refer to a cluster as "elasticsearch". would suggest removing this, and, in the definition above, we could say that it is distributable and link out to the architecture docs
also think that throwing to the reference docs does not help the user at this stage
|
|
||
| <br> | ||
| **The project type / solution view** | ||
| - {{es}} is the name of a [project type (or solution view)](/solutions/search.md) that includes UI features tailored for general-purpose search use cases: |
There was a problem hiding this comment.
do we need to specify that what it brings is UI features? could we just say "that is tailored for x"?
consider splitting this in two and defining them separately to reduce mental load
There was a problem hiding this comment.
looking at this again, I see what you wrapped them together (to connect them well to the search solution section). I still think we should split them and just link to the search section on general-purpose search use cases or something instead in each definition perhaps
|
|
||
| <br> | ||
| **The platform** | ||
| - The {{es}} [platform](https://www.elastic.co/platform) (also known as the Elastic platform or Search AI Platform) refers to various {{stack}} components deployed together with additional management affordances to power Elastic's managed services. |
There was a problem hiding this comment.
consider rolling stack into this (another former/current name of the platform, currently the docs name for the versioned platform)
|
|
||
| $$$glossary-elasticsearch$$$ {{es}} | ||
| : The open source search and analytics engine, data store, and vector database which is the core of the [{{stack}}](#glossary-elastic-stack) and powers the Elastic platform. | ||
| :::{admonition} Disambiguation |
There was a problem hiding this comment.
nitpick: disambiguation is a big word. how does "What else can Elasticsearch mean?" or something a little friendlier strike you?
| : Also known as the *ELK Stack*, the {{stack}} is the combination of various Elastic products that integrate for a scalable and flexible way to manage your data. | ||
|
|
||
| $$$glossary-elasticsearch$$$ {{es}} | ||
| : The open source search and analytics engine, data store, and vector database which is the core of the [{{stack}}](#glossary-elastic-stack) and powers the Elastic platform. |
There was a problem hiding this comment.
🤔 what if this glossary definition just had all of the disambiguation stuff in it? elasticsearch might mean any of these things: ...
Elasticsearchas being discussed in this internal doc