[DOCS] Drafted a stack-level glossary

[lcawl]

This glossary integrates terms that are currently spread across the library, as listed here:
https://wiki.elastic.co/display/DOC/Glossaries

To build this glossary, the following PR must also be implemented: elastic/docs#271

The following command can then be run:

./docs/build_docs.pl --doc stack-docs/docs/en/glossary/index.asciidoc

[nrichers]

This is awesome, @lcawl!

One suggestion: Can we include where a term came from? I see a whole slew of ECE terms that don't really apply to anything else.

[nrichers]

This sentence is getting munched in the output, probably because the name of the product isn't defined anywhere (:n: Elastic Cloud Enterprise):

[lcawl]

Good catch! I copied these from the cloud file, but changed {n} to {ece} and added the latter to our shared attributes file. Looks like I missed this guy though!

[lcawl]

@nrichers I was actually pondering that while merging the terms. Do you envisage having some kind of icon or "Applies to..." qualification? I kind of like the idea of assuming that the terms apply to the whole stack and then clearly stating the circumstances in the description if not. In some cases (e.g. node or field), terms appeared in multiple glossaries with only slight differences. If the difference seemed significant, I put the different definitions in a separate paragraph (e.g. the "In Logstash.... paragraph in the "field" definition). I'm open to better solutions though!

[debadair]

++ for identifying where terms come from. It would be extra-awesome to view the glossary alphabetically or by product. If we tag entries, that might be possible down the road. Maybe w role=xyz like we do for x-pack?

[nrichers]

@lcawl It would be easy to overwhelm the combined glossary if indicating the source of a term is too wordy ... E.g. (Source: Elastic Cloud Enterprise) kind of adds a lot of verbiage. A slightly greyed out icon with alt text might be better or perhaps just something like (ECE). Or ... is there something like alt text that can be defined on definition list entries?

(Read: Not sure. 🙂 )

[lcawl]

I think it might be possible to do a "domain" callout, similar to what we currently do for deprecations/additions/experimental content (see https://github.com/elastic/docs readme). I think I'll do that in a separate PR, however, since it might require several iterations to get it working.

[lcawl]

@debadair I changed the lower-level title to "Terminology" and added a brief introduction as you suggested.

[dedemorton]

@lcawl Nice! I think a consolidated glossary is useful to most users, but in the Logstash world we still have users who are only using Logstash (LS writes from and reads to lots of sources that are not Elasticsearch). So I want to keep the Logstash glossary in the Logstash Reference, but I don't like the idea of duplicating content that's likely to get out-of-sync over time. We need a single source of truth that we can pull the glossary items from.

[lcawl]

@dedemorton I think it should be possible to re-use the content using tagged regions if nothing else. I'll play around with that here.

[lcawl]

@dedemorton I ended up adding ifdefs in the glossary.asciidoc file (per 21.3.2 here: http://www.methods.co.nz/asciidoc/userguide.html#_block_elements).

If you wanted to re-use that content in the Logstash Reference, you would need to add something like this:

:stack-repo-dir: {docdir}/../../../stack-docs/docs/en
:logstash-terms: true
...
include::{stack-repo-dir}/glossary/glossary.asciidoc[]

And then you would need to add the stack-docs repo to the build_docs.pl command (e.g. --resource=stack-docs/docs)

I can help implement that when/if you want to use it in the Logstash Reference.

[lcawl]

The glossary is now visible here: https://www.elastic.co/guide/en/elastic-stack/glossary/current/index.html

[dedemorton]

Thanks, Lisa! I'll add it to the LS docs when the glossary file is available in the other branches.