Glossary?

[kaijagahm]

In reviewing the guide, I'm thinking we might want to have a glossary that we can hyperlink terms to. Ideally, the terms would be explained in really simple, friendly ways. The idea would be to lower the barrier to people reading this guide.

For example, I'm reviewing the section on goals of code review, and it says "This check should be carried out in an environment that is not identical to the development environment. In other words, check that the code runs on a different computer, a different operating system, or a different version of the software." The term "development environment" seems self-evident (especially since the following system gives examples of what a change to the development environment could look like), but it's just jargony enough that a few years ago I would have been left wondering whether it has a specific meaning that I'm not aware of. But because the manuscript assumes that the term is self-evident, I would have felt embarrassed for not knowing.

I'm envisioning that a separate glossary page could include an entry, something like "A development environment refers to the software conditions of the system where the code was developed. It might include things like what type of operating system you're using (Mac, Windows, etc.), whether or not you coded in RStudio or a different program, or what version of RStudio you were using."

What do people think about this idea?

[kaijagahm]

Oh, and, I'm not even totally sure that my definition here of "development environment" is correct! I was quite nervous to post it. Which just highlights, I think, why something like this would be useful.

[smweis]

I think this is a great idea!! Given that it's something for all levels, I would 100% support someone flagging terms they don't understand and dumping them into a glossary...

[debruine]

This is a really good idea. We could use the PsyTeachR glossary and add terms to it, which would embed short definitions in the text on hover, and automatically generate a glossary or all defined terms at the end of the document.