Define personas

[tombentley]

ADRs often needs to refer to groups/teams or people with a particular function (e.g. "customer support team", "support engineer" etc). We shouldn't use some private jargon for these things, so they need generic terms and to be explained somewhere.

[k-wall]

I wonder if using Glossary tooltip plugin is a way forward.

We would define an _data/actors.yml and use that to enumerate the human/system actors and provide a description. ADRs would reference those as {% actors term_name %}. The plugin generates a tooltip with the description which would help the reader understand the role of the actor. This would give us a standard way to refer to actors across ADRs and enable validations/linting.

What this wouldn't address is provide a mapping back to Red Hat organisational names.

[tombentley]

I wonder how a technical solution like that would work in practice. Training new (or even regular) contributors to the repo to use {% actors term_name %} might be a never-ending process. I can see that if we could maintain a "common lexicon" it would probably be slightly better than what we're currently trying to do with acronyms/initialisms (which is to force people to provide the expansion).

But having _data/actors.yml (or a human readable version of it), that is defining the system actors on the site would be really really useful in building that common lexicon. Once we have it, it's easier in code review to ask people to use the actors in it (e.g. where they're using other terms), or to add to it if needed.

[grdryn]

I think what I did for ADR-76 might be relevant here? Look at any reference to RHOSAK in the following page: https://architecture.appservices.tech/adr/76/

Line 14 here is how I defined that: https://github.com/bf2fc6cc711aee1a0c2a/architecture/pull/46/files#diff-c506df10ada0737a193a7f06b1344d93d08cc9eb16bd994782cacfc3b4ac2584R14