255003 - Document certificates and validation

Status: VERIFIED FIXED

(Firefox Graveyard :: Help Documentation, defect)

Description

[Jeff Walden (gone starting June 8)]

Blake removed the provisional notice for these on August 3.  We need to document
them.  I'll try my hardest to get something, but to do it correctly before 1.0PR
will be extremely hard.  I'm not even going to attempt to tackle it tonight,
because it's way later than I want it to be here.  If anyone else feels up to
it, please take this bug (but post regular updates, because then work can be at
least somewhat shared).

The best possibility for fixing this is porting from the Seamonkey docs.  I
think the UI is somewhat similar (because it was marked as provisional so long),
so that would ease that choice.  As I seem to recall Seamonkey Help docs being
all fugly, tho, removing cruft and porting to the proper language/coding/visual
style will be somewhat time-consuming.

Unlike some other bugs where I've set blocking-aviary1.0PR? requests, I'm not
particularly optimistic about this one, so I'm setting nothing.  It would be
good to remember, tho, that *something* for this is far better than *nothing*.

*As a last resort*, if we don't write anything, the Help sections certainly need
to be edited either to remove the notices of un-documentation or to remove the
sections from Help completely (even if it's only temporary until Firefox 1.0 is
out).  After all, better out of sight completely than in sight and incomplete.

Comment 1

[R.J. Keller]

Jeff, don't set any more blocking flags. Any bugs depending on the Firefox Help
tracker bug will block 1.0PR1. It's done so we don't spam the Firefox Developers
with requests.

Comment 2

[Jeff Walden (gone starting June 8)]

Attachment: Patch to minimally describe the two sections

This adds minimal descriptions of Certificates and Validation to the options
documentation.	I also added an entry for "secure site" to the glossary to help
supplement my description of certificates as the machines that encrypt and
decrypt connections to secure sites.

Comment 3

[Jeff Walden (gone starting June 8)]

Comment on attachment 156084 [details] [diff] [review]
Patch to minimally describe the two sections

Something is better than nothing...let's get this in before the l10n freeze.

With any luck these sections will be greatly simplified after 1.0.  Validation
in particular seems almost completely useless to me, or it could be combined
with Certificates.

Comment 4

[R.J. Keller]

Comment on attachment 156084 [details] [diff] [review]
Patch to minimally describe the two sections

> +  transmitted data.  When you visit secure sites, &brandShortName;
> +  displays a lock icon in the <a href="#Status_Bar">Status Bar</a> and
> +  the <a href="#location_bar">Location Bar</a>, displays the site's
> +  domain name in the Status Bar so you can verify that you're on the
> +  right site, and highlights the Location Bar in yellow.</dd>
> +

Your setence structure here is goofy. It needs to be rewritten. First off you
need to replace the "and" after Status Bar with a comma, but then the part
below sounds weird.

> +
> +  <!--XXX watch out!  changes probably coming here after Firefox 1.0 -->

You can keep this here if you want to, but I don't think anyone will read it
:).

>  <div class="contentsBox"><em>17 July 2004</em></div>
>  <p>Copyright &copy; 2003-2004 Contributors to the Firebird Help Project.</p>
>  </body>

<picky>Fix the date please :)</picky>

Comment 5

[Jeff Walden (gone starting June 8)]

Attachment: Tweaks wording, changes the correct glossary.xhtml/firebird-glossary.rdf

Okay, try this for size.  I've removed the comments, updated the dates, changed
the wording for 'secure site' to be less ugly, and made the changes to the
correct glossary files.

Comment 6

[R.J. Keller]

Comment on attachment 156107 [details] [diff] [review]
Tweaks wording, changes the correct glossary.xhtml/firebird-glossary.rdf

Much better! Thanks Jeff! r=[e-mail]

Comment 7

[Jeff Walden (gone starting June 8)]

Comment on attachment 156107 [details] [diff] [review]
Tweaks wording, changes the correct glossary.xhtml/firebird-glossary.rdf

R.J., are you on top of the CVS over SSH thing yet, or should I ask Steffen to
check this in?

Comment 8

[R.J. Keller]

(In reply to comment #7)
> (From update of attachment 156107 [details] [diff] [review])
> R.J., are you on top of the CVS over SSH thing yet, or should I ask Steffen to
> check this in?
> 

Steffen :). I think that leaf is off on weekends. I don't like this SSH
conversion. They could've at least put up a test server to test my account on!
I've already had 3 people give up on me :). Hopefully leaf can fix it on monday.

Comment 9

[Steffen Wilberg]

cvs is actually pretty stupid. The patch doesn't apply because I've landed bug
254780 before. But never mind, I already hammered this into my tree.

Comment 10

[Steffen Wilberg]

Checked in.

Comment 11

[Steffen Wilberg]

Can we improve the glossary entry for secure sites a bit? Especially this part:
"Firefox also displays the site's domain name in the Status Bar (to prevent
malicious sites from stealing your data)..."

The domain (host) name is only displayed if the lock is not "broken". Broken
security means that non-secure content is displayed as well.
Example: https://www.dab-bank.com/

We should explain the concept behind the broken lock since it looks a bit scary
if you don't know what it means. You can also double-click the lock icon to
display security information about the current page.