Clearer definitions for Open Match terms

[Evertras]

Terms like MatchProfile and even Ticket are taken for granted, either explained in the middle of a tutorial or deep in the API reference. I originally went to the Glossary after encountering "MatchProfile" with no other context around it, but only found generic cloud terms there. The Glossary may be a great place to add Open Match specific terms as well as a singular reference point.

I'm willing to do this work, but I want to make sure it's wanted before I start.

[Laremere]

Hey,
Do you think the API reference is sufficient? https://open-match.dev/site/docs/reference/api/#openmatch.MatchProfile

I would like to avoid too much repetition in the docs. If the descriptions in the API reference aren't good, we should fix those (it's hard to judge how good they are when I already understand everything.) If it's a discovery problem, we should fix that.

Thoughts?

[Evertras]

I agree on avoiding repetition, both for maintainability and clarity.

The biggest problem is certainly discoverability. I spent more time than I want to admit trying to piece together how the system works and what it wants to do. I don't think to go to the protobuf API reference to learn about concepts; to me that's where I want to go when I want to check a specific signature or get details on a data structure. If the definitions are going to live here, I need to know to look there in the first place.

For example, here in the getting started guide where it talks about demo concepts, I think a simple step up would be to link each of the concepts to the API reference entries. There are other places in the documentation where we could link these as well. I'm still willing to do that bit if it sounds good to you.

The definitions are looking more reasonable to me now that I'm looking at them again, but I think I'm falling into the same trap as you in that now that I understand what they're doing it's all more sensible. I'm not immediately sure how to improve them at this point. I'll think on it. In the meantime, I do think discoverability is a real problem that we can fix, and it may be worth renaming this issue or creating a new one to make it more actionable in that regard.

[Evertras]

In the vein of discoverability, it may also make sense to rename the "Matchmaking Guide" to "Architecture Overview" or something similar. I really wanted a high level overview of what the system is doing and what's driving it but couldn't immediately figure out what was important and what I should be paying attention to.