[DOCS] Use single source for Elasticsearch glossary

[jrodewig]

We currently duplicate glossary terms for Elasticsearch in two places:

• Elasticsearch Reference glossary
• Elastic Stack Glossary

Per @lcawl's suggestion in elastic/stack-docs#34, we should consolidate terms in the Elastic Stack Glossary and use include:: to pull them in.

Caveats

@lcawl pointed out that this will create a dependency between the ES Reference and the Elastic Stack glossary.

A non-exhaustive list of options to address the dependency:

• Update the Doc Build aliases to explicitly list the stack-docs repo as a resource.
• Relocate the Elastic Stack glossary to the /elastic/docs repo.

@nik9000 let me know if you have any input on the preferred approach.

[elasticmachine]

Pinging @elastic/es-docs

[nik9000]

Relocate the Elastic Stack glossary to the /elastic/docs repo.

This seems like it'd impact the fewest folks. Just because the list of folks that hack on the Elasticsearch repo is much larger than the list of folks that hack on the stack-docs repo. Adding the dependency in the aliases is actually more complex than it looks because we use those for the PR builds that build the docs and we'd need to clone the stack-docs repo there. Possible, but complicated. My "universal" docs PR testing thing would pick it up automatically, but that still leaves the issue of folks wanting to build the docs locally. The whole ES team would have to keep the stack-docs repo up to date. That doesn't seem worth it.

[jrodewig]

Thanks @nik9000. Glad I asked as I wasn't aware those aliases were also used for PR builds.

I'll plan to relocate the Stack glossary to the /elastic/docs repo.

[lcawl]

For the record, I think you don't necessarily have to move the book (index.asciidoc, etc). Rather, you can just move the content... similar to what we've done with other shared content like https://github.com/elastic/docs/blob/master/shared/settings.asciidoc

[nik9000]

We don't do proper change detection on asciidoc files in the docs repo so I'd prefer to move the content to the elasticsearch repo I think. What about if we had an elasticsearch glossary that we included in the book in stack-docs? Then we could have a kibana and beats glossary that we include there as well if we need it. I expect all of the stack projects have glossary terms!

…

On Wed, Mar 27, 2019, 17:24 Lisa Cawley ***@***.***> wrote: For the record, I think you don't necessarily have to move the book (index.asciidoc, etc). Rather, you can just move the content... similar to what we've done with other shared content like https://github.com/elastic/docs/blob/master/shared/settings.asciidoc — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#40560 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AANLogvn1cvKYHLKrnoVGaIUdONvEKjaks5va-GigaJpZM4cOvJs> .

[lcawl]

If we're pulling from multiple repos into a single glossary list, it becomes harder to keep the terms sorted.
There are lots of options here for you to play with, @jrodewig hope you're still having fun!

[jrodewig]

😅 Definitely still fun!

I agree with Lisa that sorting incoming terms from multiple glossaries would be a problem. It's also an issue if a term is listed in more that one glossary. A good example is cluster, which is currently in both the elasticsearch and cloud glossaries.

I'll work on a few PRs to house the glossary in the docs repo for now. If we run into issues, I can look at either relocating it back to the elasticsearch repo or some other place.

[jrodewig]

This work effort will include PRs for the following:

1. Move Stack glossary content from the /elastic/stack-docs/ repo to /elastic/docs/. See [DOCS] Copy glossary content from Stack Docs glossary docs#759
2. Update the Elasticsearch glossary.asciidoc file to include:: terms from the /elastic/docs/ glossary
3. Update the /elastic/stack-docs/ glossary.asciidoc file to include:: terms from the /elastic/docs/ glossary content.

[jrodewig]

We discussed this internally and decide to go with a many-to-one approach (individual solution repos feeding into a combine glossary).

Closing this ticket. Will open other tickets to handle the new approach.