Seed a glossary

[dnadales]

Motivation: we usually write documentation (both in the website, but also in our GitHub issues) that refers to frequently used concepts (eg Chain Growth Property, Active Slot Coefficient). Both readers and writers would benefit from having such a glossary: the writers can easily refer to these concepts without having to explain then over and over, and the readers can have a handy reference they can use when they find an unknown concept.

[dnadales]

Rendered pages:

In this example, one of the references links to the other.

[nfrisby]

I posted a suggestion in a GitHub comment.

Also, the Tweag Genesis team developed a big glossary when @amesgen and I were onboarding the new members. I'm pretty confident we could just copy that over.

What do you think?

[nfrisby]

I suspect that we'll end up with several tens of these terms.

So I propose a single Glossary.md file, in which people can use CTRL-F to find something. And hopefully HTML anchors will let us link to specific definitions within that file.

[dnadales]

Good point. I'll add that file. The only problem is that linking to files not in the sidebar makes it disappear. So I'll see if I can figure out a way to solve this.

[dnadales]

This is not great because people would need one extra click to access the index, but it's the only option I could find.

[dnadales]

I posted a suggestion in a GitHub comment.

Also, the Tweag Genesis team developed a big glossary when @amesgen and I were onboarding the new members. I'm pretty confident we could just copy that over.

What do you think?

I think that's a great idea! Should we do it in a follow-up PR to keep the scope small?

[nfrisby]

I hope to open a PR with the lexicon ASAP---just waiting for the go ahead. I suspect it supersedes this PR (eg it has these two entries already), but I'll leave that for you to judge :)

[dnadales]

Waiting on Tweag glossary.

[nfrisby]

I sent you the Tweag lexicon, on Slack. (Clarke and Kowalsky on the Tweag side both said it'd be fine for me to do that.)

[nfrisby]

Looks great; thanks for reformatting.

One minor comment, about structure/maintainable as opposed to content.

[nfrisby]

Minor suggestion: If every wiki-ish links like the ones you've added is targeting this same document, then my intuition is that we don't need them.

• They'll be a burden to maintain if we rename things, etc.
• They make the Markdown itself less legible.
• If someone is reading a description on this page and they see a word they don't recognize/etc, they should be able to CTRL-F to find its definition. To make this easier, we could add a symbol that's unique to the definition of the word, such as ## defn:Block and so on. So if you want to find the definition of a word foo, you CTRL-F for defn:foo. (A very tame JavaScript one-liner can automate this: document.querySelectorAll("h2").forEach(function (e) { e.innerHTML = "defn:" + e.innerHTML.trim(); }) eg at https://jsfiddle.net/c8ustjzh/.) Or maybe some cheeky symbol, such as ‡ instead of defn:?

That'd be much less noisy, easier to maintain, and only slightly less convenient to use.

[dnadales]

They'll be a burden to maintain if we rename things, etc.

I think Docusaurus check for broken links. We still have to fix these, but I don't think we'll change headings such a ## Slots very often.

[dnadales]

they should be able to CTRL-F to find its definition

This might be a problem. For instance, consider the word "slot" or even the mention of k or scg. It might take ~1 minute to hit CTRL-F till they find the right definition. So we need at least at defn:foo in the headers, as you suggested.

Or maybe some cheeky symbol, such as ‡

I think it's better if we use something people can easily type :D

[nfrisby]

## :block
## :slot
## :header

would probably suffice IMO and not be too much visual noise.

I think it's better if we use something people can easily type :D

Good point! It will at least essentially always be on the screen and so possible to copy onto the clipboard 🤷

[nfrisby]

I suggest: we use simply the leading colons.

Bonus script at the bottom of the file to make them visually softer than the word: document.querySelectorAll("h2").forEach(function (e) { e.innerHTML = e.innerHTML.replace(':','<span style="color: rgba(0, 0, 0, 0.5);">:</span>';) })