Ethereum-org-website: Glossary

[marcgarreau]

Is your feature request related to a problem? Please describe.
:wave: Hi there. We speak our own language: dapps, mainnet, smart contracts, etc. ad infinitum. When I'm writing documentation, I look to link out definitions of buzzwords. Would love those links to be pointed to ethereum.org for posterity and SEO.

Describe the solution you'd like
Any form of glossary; definitions in layman's terms would be a great start. Could always be expanded with related links or whatever else feels appropriate.

Describe alternatives you've considered
I link out to sections/subsections of ethereum.org pages where possible. Otherwise, its the next best resource I can find for the topic.

Obviously this effort has been undertaken in different forms over the years. I think the biggest selling point for reinventing this wheel is more inbound links and SEO.

[samajammin]

Thanks for the suggestion @marcgarreau! Completely agree - lot's of jargon in this space. I'd love to help make this a reality.

Here's a few potential places we could gather inspiration from for this feature:

• https://sidewaysdictionary.com/
• https://www.investopedia.com/financial-term-dictionary-4769738
• https://bitcoin.org/en/vocabulary
• https://developer.bitcoin.org/glossary.html

Another idea we've discussed internally is having a tooltip-on-hover interaction that defines Ethereum jargon without breaking the user's flow by forcing them to a new page. I think Wikiwand (a Wikipedia skin) does this well.

Here's the result of hovering the mouse over "open source" - it provides brief explanation with a link to the in-depth article:

I don't think the toolip feature would solve for your use case though (linking to a reference for definitions). Perhaps we should do both 😄

[samajammin]

@all-contributors please add @marcgarreau for ideas.

[allcontributors[bot]]

@samajammin

I've put up a pull request to add @marcgarreau! :tada:

[marcgarreau]

As you suggest, the wand is a bit orthogonal to the glossary request, but it might be a good fit for some contexts. As an example, I was wondering how obvious the definition of the term Mainnet is. My suspicion is that some readers could benefit from a proper definition. Typing it in the search bar first brings you to the Enterprise page, which does make the assumption that no definition is required there. This might be a nice place to provide a definition on hover. (Side-note bug report: the top of the page contains Page last updated: Invalid date)

Edit: re: sideways dictionary, just discovered that EthHub has a sparse one: https://docs.ethhub.io/glossary/sideways-dictionary/smart-contract/.

[samajammin]

Agree re: mainnet definition.

Thanks for reporting the bug! We solved that in #1203

[ryancreatescopy]

Thanks for the suggestion @marcgarreau! Completely agree - lot's of jargon in this space. I'd love to help make this a reality.

Here's a few potential places we could gather inspiration from for this feature:

• https://sidewaysdictionary.com/
• https://www.investopedia.com/financial-term-dictionary-4769738
• https://bitcoin.org/en/vocabulary
• https://developer.bitcoin.org/glossary.html

Another idea we've discussed internally is having a tooltip-on-hover interaction that defines Ethereum jargon without breaking the user's flow by forcing them to a new page. I think Wikiwand (a Wikipedia skin) does this well.

Here's the result of hovering the mouse over "open source" - it provides brief explanation with a link to the in-depth article:

I don't think the toolip feature would solve for your use case though (linking to a reference for definitions). Perhaps we should do both 😄

Wonder if we could utilise any existing packages to do this idea. Here's a couple I found after a quick npm search:
https://www.npmjs.com/package/glossarify-md#term
https://www.npmjs.com/package/glossarizer

[github-actions[bot]]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days

[wackerow]

Another possible source of inspiration could be the Mastering Ethereum book, by Andreas Antonopoulos and Dr. Gavin Wood, which has a nice glossary and the repo is on GH under a Creative Commons license: https://github.com/ethereumbook/ethereumbook/blob/develop/glossary.asciidoc

Since this went stale, I can take a look at maybe starting with just a reference page to address the initial post.

[samajammin]

Another glossary source: https://ethdocs.org/en/latest/glossary.html

License is also CC: https://github.com/ethereum/homestead-guide/blob/master/LICENSE-CC-BY-SA-4-POINT-0

[samajammin]

Solved in #1673!

Track #1717 & #1718 for further improvements.

[marcgarreau]

v1 is looking great already! thanks all 🏆