docs: Review terminology used and make docs more accessible

[anderseknert]

A number of users on Slack as well as our Github discussion board have expressed that they find the terminology used in the documentation difficult to grasp. Some of the words used there might only be understood given a background with some specific programming language or domain, and could be improved by using either alternative words, inline hover explanations, or a glossary of common terms.

Examples provided include things like "comprehensions", which isn't a concept known to many outside of Python, "marshalling" instead of "serialization" etc..

Obviously anyone can just research the meaning of terms used outside of our docs, but it would be nice if we provided this ourselves to avoid needless context switching while learning.

[anderseknert]

Apparently there’s a CNCF project to build a “cloud native glossary”. I wonder if we could contribute to / use that.

https://www.cncf.io/blog/2022/01/11/join-the-cncf-cloud-native-glossary/

[stale[bot]]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days.

[anderseknert]

From the OPA Slack today:

in the docs, there's headings for "Scalar Values", "Strings", and "Composite Values". This doesn't make the variable type hierarchy totally clear, and for idiots like me who haven't heard the term "Scalar Value" before, it's hard to figure out where to click to learn more about "whatever the number data type is called"

Also, none of these sections seem to include documentation on arrays

[stale[bot]]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days.