Skip to content

Inquiries examples need semantic cleanup #946

Open

Description

@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.

Activity

  1. mweinberg-cm commented on Apr 24, 2020

    @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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions