753016 - “How it works” page doesn't explain how it works

Status: RESOLVED INCOMPLETE

(Cloud Services :: Server: Identity, defect)

Description

[Grey Nicholson (they/them)]

The “How it works” page doesn't actually explain how BrowserID works—it only explains how to use BrowserID.

This is an important distinction:

“Hey, $proprietary-software-vendor! How does $important-software work?”
— “You just press the button!”
“Gee, thanks, $proprietary-software-vendor! It really is that simple! I'm now in full control of my proprietary software, yessirreebob.”

—or—

“How does my vote get counted?”
— “It just does!”
“High five!”

—or—

“Good day, Newton! How worketh gravity?”
— “It maketh things fall.”
“Truly, I am enlightened.”

We want to encourage people to View Source, and understand how things work.

We should change the link to say “How to use BrowserID” or “Step by step” or some-such.

Workaround: The “Need Help?” link at the bottom of the page leads to…
https://support.mozilla.org/en-US/kb/what-browserid-and-how-does-it-work#w_how-does-it-work
…which does (mostly) explain how it works.

Comment 1

[Liz Henry (:lizzard) (relman/hg->git project)]

Hi Greg, I just came across this while searching for a different bug, and noticed you haven't had any answer yet. Do you mean the How it Works link from this page?
https://login.persona.org/ ? That leads here: https://login.persona.org/about  which certainly is simplified. The About page does have a link at the bottom to the developer documentation, which has quite a lot of information about how it works. Do you think that is sufficient to address your concerns?   

If the persona.org/about text should be changed, we may also want to move this bug report over to a different component. Thanks!

Comment 2

[Grey Nicholson (they/them)]

Hi Liz,

Yes, that's the link. My thinking originally was that the link's text should not be “How it works”; because the page doesn't actually explain how Persona works. Instead the link should be labelled “How to use it” or something similar, because that's what the page explains — which is good and useful, but different.

However, looking at the current text on persona.org/about, I think the page is actually closer to “Why Persona is genius”, or more mundanely “Why choose Persona?”.

I think it's important that when we say “how it works”, we really do mean “here's how we did it; any suggestions?”. We should hold ourselves to a higher standard than our competitors, and encourage our users not to accept shiny, hand-wavy answers like “it just works; stop asking questions”.

Comment 3

[Liz Henry (:lizzard) (relman/hg->git project)]

Greg, thanks! I asked in irc and got this advice:

open an issue here: https://github.com/mozilla/browserid/issues?state=open, add the 'area:docs' label to it, and link to the new github issue from bugzilla. 

Would you like to do this? If not, I am happy to, but since you might like to track it on github, I thought I'd ask.

Comment 4

[Jed Parsons (use needinfo, please) [:jedp, :jparsons]]

Hi, that was me (jedp) on IRC giving that advice.  Please let me know if you have questions.  Cheers!

Comment 5

[Grey Nicholson (they/them)]

(In reply to Liz Henry :lizzard from comment #3)
> Greg, thanks! I asked in irc and got this advice:
> 
> open an issue here: https://github.com/mozilla/browserid/issues?state=open,
> add the 'area:docs' label to it, and link to the new github issue from
> bugzilla. 
> 
> Would you like to do this? If not, I am happy to, but since you might like
> to track it on github, I thought I'd ask.

Liz,

I'd very much appreciate it if you could open the issue on GitHub — I'm one of the eleven or so people here who don't already have a GitHub account and I'd like to avoid creating yet another account on yet another unfederated proprietary web service. :)

Also, thanks for responding so many orders of magnitude more promptly than me, and for continuing to be generally awesome. (And thanks, Jed and François, for putting the effort in to help with my drive-by participation.)

Comment 6

[Austin King [:ozten]]

What are you concrete suggestions?

The "How it works" section is targeted at end users.

The MDN docs are targeted at a technical audience.
https://developer.mozilla.org/en-US/Persona?redirectlocale=en-US&redirectslug=Persona

There are several open bugs regarding this topic, I don't think we need another one without steps to reproduce or concrete input.
https://github.com/mozilla/browserid/search?q=how+it+works&ref=cmdform&state=open&type=Issues

Thanks for our input!