I agree with @callahad's suggestion. I think in this case, we should update the doc, for the reasons stated in https://github.com/mozilla/browserid/pull/3116/#issuecomment-15126374