Inquiries examples need semantic cleanup

[blag]

We use the term "second factor" and "authentication" in the documentation, but the usage of those two terms is confusing and slightly misguiding for users.

Every example of what we call "authentication" in the Inquiries section is actually a form of authorization. I realize that we should probably have at least one example that is different from a generic approval inquiry, but using the wrong word for the same concept really isn't a very instructive example for users.

Additionally, we should shy away from using the term "secondfactor", as it also seems to refer to "multi-factor authentication" (MFA) just using a different name, and all of those examples are similarly not actually illustrating authentication but authorization. I haven't seen any users using inquiries besides asking for a second approval, so restricting our examples to that use case should be fine for now. As we collect more feedback and more use cases we can create additional examples beyond the simple approval flow.

I realize that this is literally arguing over semantics, but words generally have distinct meanings and misusing terms to boost the count of our examples only serves to confuse and intimidate users against using inquiries in the first place.

[mweinberg-cm]

Hi @blag,

first of all, I'm not a native speaker but I'll do my best to get this done.

I took a look at https://docs.stackstorm.com/inquiries.html and most of the cases where authentication and second factor is used seem legit to me. I understand it as the second factor (i.e. an auth token) to be used to authenticate to another service. In this case I think the wording is fine.
At the same time I agree that the examples can be a bit misguiding and we may wanna provide examples for another use-case.

Can you go a bit more into the details and share an example where you would like to see an improvement?

I'd be happy to come up with a draft for the docs once we agreed on a way to go as I strongly agree with the last sentence of your post.