Clarify TOTP setup instructions

[iandunn]

I think the current instructions will confuse many folks who are new to TOTP or 2FA in general.

They assume that folks have setup TOTP before, so they several steps of the process. The introduction feels like a run-on sentence, which could overwhelm folks who need to go slower. The secret isn't labeled, so it could also be confusing to folks who haven't seen one before.

Breaking it into steps could help a lot. Here's a very rough sketch of what that could look like:

That still needs a lot of visual formatting and refinement, but hopefully it conveys the general idea.

[pbiron]

In general, I think the direction of the "rough sketch" is great.

One minor quibble: authenticator apps do not have to be on a phone. For example, Authy has a desktop version (which can sync accounts to their mobile version)...that's what I use.

So, I'd suggest something like:

Step 1: Install an authenticator app on your desktop/laptop and/or phone....

[iandunn]

Yeah, that's a fair point 👍🏻

[r-a-y]

Yeah, I agree with this.

On our two-factor install, we modified the first line to:

Please scan the QR code or manually enter the key into your authenticator app. Next, enter the authentication code from your app to complete set up.

We also prefixed the key with <strong>Key: </strong> and changed the "Submit" button text to "Complete Set Up".

[dd32]

It's worth noting that step 2 of "Install a QR code scanner app" in the rough sketch above isn't normally a separate step, it's built in to most (all?) of the authenticator apps.

With the addition of #487 it might be also worth noting that Mobile users (and I guess desktop app users..) can click the QR to load their app usually.

[dd32]

For comparison of what users may be accustomed to already, I'm including some Screenshots of other platforms where TOTP is implemented.

Notably

• They all seem to preference mobile devices - I think this is two-fold, while you can use a desktop app, none of them really want you to use a desktop app, as compromised desktops are a thing more than phones, and mobile devices are more likely to travel with the person allowing them access to the account elsewhere
• They don't show the TOTP key unless needed, behind a "can't scan" link, I suspect possibly to remove any notions a scary alphanumeric string will convey, where as since you can't read a QR it's a little more "magic"
• The GitHub and Microsoft implementations use a shorter key
• The capitalisation and spacing of the key displays below were retained, even though I changed the contents.

WordPress.com	GitHub	Microsoft	Google	Amazon