Add academic-centric glossary

[psokolhessner]

Is your feature request related to a problem? Please describe.
GitHub terms are often couched in language oriented at software developers, and some are not intuitive to figure out. There are also few resources to explain how GitHub works that take an academic-science-centric approach. Finally, the mapping from classic academic elements (like lab, study, etc) to GitHub terms is not immediately apparent.

Describe the solution you'd like
Add an academic-centric glossary that provides interpretations of some major GitHub related terms in relatively plain language that academics will readily understand.

Describe alternatives you've considered
I'm unaware of any other glossaries that similarly make GitHub terms accessible to academics.

Additional context
Thinking about the basics: repository, organization, issue, branch, commit, push, pull request, labels, merge... possibly also other GitHub elements like projects, actions, etc (I haven't used them, and so don't know how they'd fit in to an academic framework).

Such a straightforward glossary, even if brief, could provide a nice complement to detailed guides about how to use GitHub, and best practices with respect to those elements (e.g. what makes a good commit, when to do commits, etc).

It could also be very valuable in terms of allowing new users to cut through jargon, and hear someone 'speak to them' in their 'language', facilitating the use of other SYL materials.

[aridyckovsky]

@psokolhessner do you have a sense of whether this might fit best as one of the following?:

• A subsection of "Useful Concepts"
• A subsection of "Resources"
• A blog post

Or, were you thinking that it becomes a standalone section in the Docs, such as a sidebar tab (and associated document) called "Glossary" or similar?

[psokolhessner]

@aridyckovsky I had pictured a standalone, as this information is potentially vital to so much of SYL's mission (and to GitHub noobs visiting SYL; the 'signal' of the presence of a glossary may be worthwhile). If effective, I can also see this document being referenced by all sorts of other guides & docs (setting up the lab organization could link to this document to define/clarify repositories and organizations; documents about and best practices for how to use branching & merging effectively in an academic workflow; blog posts about GitHub-related concepts) in addition to being valuable on its own as a "hey, are you confused about what people mean when they talk about X, Y, or Z in GitHub? We have a glossary for that!"

That said, it does seem like it could very naturally fit under "Resources". Seems less of a "useful concept" to me, just b/c it'll be so general/unfocused relative to things like text editors, etc.

[aridyckovsky]

That sounds great @psokolhessner. I think given the potential significance of the glossary, it should live on its own. This provides two advantages over the natural fit within "Resources":

1. Given our uncertainty of where general resources will live at the moment, nesting a big item like the glossary seems like a recipe for future headaches and required client redirects, and
2. It's very possible that we'll want to include something beyond a definition for each term, and decreasing hierarchy to each term's page or section will be a long-term win.

Both of these points relate to #39, which will index the glossary and its pages/sections as its own area of the site. You can see this style of search in action via the navigation bar on https://docusaurus.io/

[psokolhessner]

Nice re: #39!

I'd suggest consideration of a careful and limited definition of scope for the glossary - to provide definitions/interpretations of 'terms of art' (I think primarily of GitHub, b/c it's where I'm least comfortable, but could also apply to Slack or anything else SYL seeks to teach) in plain language focused on linking these terms to common objects or events in social science research and collaboration. Anything beyond that (e.g. any detailed "how" or anything more comprehensive like a description of a recommended GitHub workflow) should possibly live elsewhere.

The version of this I'm imagining is a relatively simple, straightforward, and succinct document that people encounter early on, in their first forays into these tools. The document's job is to take an abstract, foreign landscape, and help social scientists see all the concrete signposts they recognize and understand. Users may come back a few times, as they learn more and start to use things more often, but before long, the glossary becomes useless to them as their comfort & knowledge outgrows it - though they may share it with any new people as a "get oriented" tool.

Just my perspective!

[aridyckovsky]

Ah okay, I have a better picture now of what you're envisioning @psokolhessner. I think what might make the most sense right now is to make this part of the docs at /docs/glossary. Given the limited scope conceptualization of it, we needn't establish a new route just yet and instead should leverage a tighter association to the items people will most likely be looking at when in need of a glossary.

For now, I'll get this started as a simple markdown file that encompasses everything, and puts the link to it within the docs sidebar as an item labeled Glossary. I'm also open to Glossary of Terms, but I'm not sure if that increased specificity is needed.

[aridyckovsky]

Adding a reference to glossarify-md here in case this becomes a large glossary and we want to make it much easier to navigate. Takes some slight configuration, so not a priority item. https://github.com/about-code/glossarify-md

[aridyckovsky]

How does this look as a starting placement @psokolhessner?

[psokolhessner]

Looks terrific, @aridyckovsky