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

RESOLVED INCOMPLETE

Status

RESOLVED INCOMPLETE
6 years ago
5 years ago

People

(Reporter: gkn, Unassigned)

Tracking

Firefox Tracking Flags

(Not tracked)

Details

(Reporter)

Description

6 years ago
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.
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!
Flags: needinfo?(bugs)
(Reporter)

Comment 2

5 years ago
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”.
Flags: needinfo?(bugs)
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.
Flags: needinfo?(bugs)
Hi, that was me (jedp) on IRC giving that advice.  Please let me know if you have questions.  Cheers!
Component: Identity → Server: Identity
Product: Mozilla Labs → Mozilla Services
(Reporter)

Comment 5

5 years ago
(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.)
Flags: needinfo?(bugs)

Comment 6

5 years ago
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!
Status: NEW → RESOLVED
Last Resolved: 5 years ago
Resolution: --- → INCOMPLETE
You need to log in before you can comment on or make changes to this bug.