Closed Bug 459566 Opened 16 years ago Closed 15 years ago

Help misnames the Certificate Manager Servers tab

Categories

(SeaMonkey :: Help Documentation, defect)

defect
Not set
minor

Tracking

(Not tracked)

RESOLVED FIXED
seamonkey2.0b2

People

(Reporter: seamonkey, Assigned: InvisibleSmiley)

References

Details

Attachments

(1 file, 6 obsolete files)

User-Agent:       Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.1b2pre) Gecko/20081011 SeaMonkey/2.0a2pre reconfigured by user.js v1.1
Build Identifier:  

http://mxr.mozilla.org/comm-central/source/suite/locales/en-US/chrome/common/help/certs_help.xhtml

In the above file the Servers tab is wrongly named "Websites" tab in anchors on lines 224 and again on line 266. Then on line 193 there is one more reference to what in fact is the Servers tab.

Reproducible: Always
Should we mention "servers" instead of "websites" in the text/toc as well?
Blocks: 423281
Status: UNCONFIRMED → NEW
Ever confirmed: true
Version: unspecified → Trunk
There's more to do than just that:
- "Other People's Certificates" has been renamed to "People"
- there's a new "Others" tab

I think we could do it all in this bug since just fixing that one name change doesn't really make it better. However the other changes probably need more time and discussion.
Attached patch proposed patch (obsolete) — Splinter Review
For now I simply changed the tab names. Since I don't know what the Others tab is intended for I didn't add anything for it in order to not make it worse (no information is better than wrong information).
Assignee: nobody → jh
Status: NEW → ASSIGNED
Attachment #369854 - Flags: review?(stefanh)
+<p>The Servers tab in the Certificate Manager displays certificates you have
   on file that identify websites.</p>

Will this be confusing for users ("server" vs "website" in many places)?
(In reply to comment #4)

> Since I don't know what the Others tab
> is intended for I didn't add anything for it

Ian, can you shed some light on the purpose of this tab?
See bug 398549 comment 6 for the reasoning behind the renaming of "Other People's"/"Extra" to "People"/"Others" and the different meanings. Unless someone can give me an example of a certificate that fits into the Others category I think we can mostly ignore it or maybe add just a short note. Opinions, suggestions?

See bug 387480 comments 52-67 for the reasoning behind the renaming of "Internet Sites" (formerly "web sites") to "Servers". That said I feel that we should use "server(s)" in all cases where the context allows types of servers other than web sites, e.g. mail servers (think IMAPS etc.). I'll take a closer look, but not today. ;-)
(In reply to comment #6)
> (In reply to comment #4)
> 
> > Since I don't know what the Others tab
> > is intended for I didn't add anything for it
> 
> Ian, can you shed some light on the purpose of this tab?

As the text in the tab says:
"You have certificates on file that do not fit in any of the other categories:"

So I would suggest something that reflects that in the help.
Attachment #369854 - Flags: review?(stefanh)
Comment on attachment 369854 [details] [diff] [review]
proposed patch

Removing request per comments.
Attached patch tabs and buttons (obsolete) — Splinter Review
This got intimidatingly huge and I guess it needs some discussion but I'd rather fix this once and for all. Noteworthy:
- changed the internal "id" attribute values to match the new naming scheme but kept the old values for the externally used "ID" attribute values in suite-toc.rdf and help-index1.rdf
- made the Help button on the Others tab do the right thing
- added descriptions for all buttons available per tab
- renamed the "That Identify..." sidebar entries as per bug 406551 comment 16
- used "Web Site" in "Edit Web Site Certificate Trust Settings" to match the title of the described dialog
- consistently used "see the description of the Certificate Manager's XY tab" because simply "see XY" is a bit short if XY is People or Servers
Attachment #369854 - Attachment is obsolete: true
Attachment #378100 - Flags: review?(stefanh)
Comment on attachment 378100 [details] [diff] [review]
tabs and buttons

Sorry for the long delay :/

+  you won&apos;t need it again for the purposes of identifying a website or
+  mail server and setting up an encrypted connection.</p>

Hmm. Do we mean "setting up an encrypted connection *and* identifying a website or mailserver"? In that case, it might be better having it like this (other way around). If we don't mean "and", you could use commas and say "or" ;-)

+<p>The Others tab in the Certificate Manager displays certificates you have
+  on file that do not fit in any of the other categories.</p>

Maybe give an example here? Not sure what that would be, though.



          nc:name="website identity"
-         nc:link="using_certs_help.xhtml#managing_certificates_that_identify_websites"/>
+         nc:link="using_certs_help.xhtml#managing_certificates_that_identify_servers"/>

Should we add "server identity"?

----------------------------------------------------------------------
I'd like to bring up a discussion about the intro in all sections:

 <ul>
   <li>If you can&apos;t see certificate names under an organization&apos;s
     name, double-click the name.</li>
   <li>To select a certificate, click its name.</li>
   <li>To select more than one certificate, hold down the Control key and click
     their names.</li>
 </ul>

We could skip the text about how to select - it is not necessary, because that's general behaviour and it's also a bit OS-dependent what key should be pressed for multiple selections (the current text is wrong for mac since mac uses the cmd key for multiple selection). Also, the current description misses the fact that you could press Shift to select multiple certs by one click ;-) 

Instead, we could just mention somthing about how to expand the list and that if you have selected multiple certificates, certificate manager will display info about them one-by one (or something).

You could then describe the buttons in the right order which would imo be better for the user.

Does this makes sense?
(In reply to comment #11)
> (From update of attachment 378100 [details] [diff] [review])
> Sorry for the long delay :/

I hope you are well.

> +  you won&apos;t need it again for the purposes of identifying a website or
> +  mail server and setting up an encrypted connection.</p>
> 
> Hmm. Do we mean "setting up an encrypted connection *and* identifying a website
> or mailserver"? In that case, it might be better having it like this (other way
> around). If we don't mean "and", you could use commas and say "or" ;-)

Well, I was just replacing "website" by "website or mail server". What I was understanding here was that one would use a certificate to identify a server and then setup an encrypted connection to it, in that order. Swapping the two sides of the "and" would be illogical with that in mind. Since "mail server and setting up an encrypted connection" alone makes no sense I think people will understand how to read the sentence.

> +<p>The Others tab in the Certificate Manager displays certificates you have
> +  on file that do not fit in any of the other categories.</p>
> 
> Maybe give an example here? Not sure what that would be, though.

Exactly that is the problem. I didn't find one either, neither in the bug that introduced that Others tab nor anywhere else. I'd love to give an example, really, but I can't.

>           nc:name="website identity"
> -        
> nc:link="using_certs_help.xhtml#managing_certificates_that_identify_websites"/>
> +        
> nc:link="using_certs_help.xhtml#managing_certificates_that_identify_servers"/>
> 
> Should we add "server identity"?

Like this?
<rdf:li>
 <rdf:Description ID="Certificates:server"
  nc:name="server identity"
  nc:link="using_certs_help.xhtml#managing_certificates_that_identify_servers"/>
</rdf:li>

> I'd like to bring up a discussion about the intro in all sections:
> 
>  <ul>
>    <li>If you can&apos;t see certificate names under an organization&apos;s
>      name, double-click the name.</li>
>    <li>To select a certificate, click its name.</li>
>    <li>To select more than one certificate, hold down the Control key and click
>      their names.</li>
>  </ul>
> 
> We could skip the text about how to select - it is not necessary, because
> that's general behaviour and it's also a bit OS-dependent what key should be
> pressed for multiple selections (the current text is wrong for mac since mac
> uses the cmd key for multiple selection). Also, the current description misses
> the fact that you could press Shift to select multiple certs by one click ;-) 

Agreed. Only the hint on how to show certificates under an organization's name is really needed.

> Instead, we could just mention somthing about how to expand the list and that
> if you have selected multiple certificates, certificate manager will display
> info about them one-by one (or something).

It seems it actually processes them one after the other, at least View opens only one dialog and closing it opens the next and so forth. Maybe we shouldn't go into too much detail here and just say that selecting multiple certificates is possible and that the different actions support it as well.

> You could then describe the buttons in the right order which would imo be
> better for the user.

Probably. Possibilities:
- keep the These actions do not require a certificate to be selected" separator and just sort within the separate bullet lists (not much won)
- transform the separator into a note ("This action does not require a certificate to be selected.") to be appended to the respective button names (better, quite a bit of overhead)
- add an asterisk (*) behind the respective button names and repeat that sign at the beginning of the separator which will not separate anymore but just explain (IMO best. Do we use that kind of "footnoting" somewhere else in Help?)
(In reply to comment #12)
> (In reply to comment #11)
> > (From update of attachment 378100 [details] [diff] [review] [details])
> > Sorry for the long delay :/
> 
> I hope you are well.
> 
> > +  you won&apos;t need it again for the purposes of identifying a website or
> > +  mail server and setting up an encrypted connection.</p>
> > 
> > Hmm. Do we mean "setting up an encrypted connection *and* identifying a website
> > or mailserver"? In that case, it might be better having it like this (other way
> > around). If we don't mean "and", you could use commas and say "or" ;-)
> 
> Well, I was just replacing "website" by "website or mail server". What I was
> understanding here was that one would use a certificate to identify a server
> and then setup an encrypted connection to it, in that order. Swapping the two
> sides of the "and" would be illogical with that in mind. Since "mail server and
> setting up an encrypted connection" alone makes no sense I think people will
> understand how to read the sentence.

OK.

> 
> > +<p>The Others tab in the Certificate Manager displays certificates you have
> > +  on file that do not fit in any of the other categories.</p>
> > 
> > Maybe give an example here? Not sure what that would be, though.
> 
> Exactly that is the problem. I didn't find one either, neither in the bug that
> introduced that Others tab nor anywhere else. I'd love to give an example,
> really, but I can't.

OK, I get it. But maybe we could mention what the Others tab certificates not are?

> 
> >           nc:name="website identity"
> > -        
> > nc:link="using_certs_help.xhtml#managing_certificates_that_identify_websites"/>
> > +        
> > nc:link="using_certs_help.xhtml#managing_certificates_that_identify_servers"/>
> > 
> > Should we add "server identity"?
> 
> Like this?
> <rdf:li>
>  <rdf:Description ID="Certificates:server"
>   nc:name="server identity"
>  
> nc:link="using_certs_help.xhtml#managing_certificates_that_identify_servers"/>
> </rdf:li>

Yes, I was also thinking we could keep the old.

> 
> > I'd like to bring up a discussion about the intro in all sections:
> > 
> >  <ul>
> >    <li>If you can&apos;t see certificate names under an organization&apos;s
> >      name, double-click the name.</li>
> >    <li>To select a certificate, click its name.</li>
> >    <li>To select more than one certificate, hold down the Control key and click
> >      their names.</li>
> >  </ul>
> > 
> > We could skip the text about how to select - it is not necessary, because
> > that's general behaviour and it's also a bit OS-dependent what key should be
> > pressed for multiple selections (the current text is wrong for mac since mac
> > uses the cmd key for multiple selection). Also, the current description misses
> > the fact that you could press Shift to select multiple certs by one click ;-) 
> 
> Agreed. Only the hint on how to show certificates under an organization's name
> is really needed.
> 
> > Instead, we could just mention somthing about how to expand the list and that
> > if you have selected multiple certificates, certificate manager will display
> > info about them one-by one (or something).
> 
> It seems it actually processes them one after the other, at least View opens
> only one dialog and closing it opens the next and so forth. Maybe we shouldn't
> go into too much detail here and just say that selecting multiple certificates
> is possible and that the different actions support it as well.

Yes, sounds good.

> 
> > You could then describe the buttons in the right order which would imo be
> > better for the user.
> 
> Probably. Possibilities:
> - keep the These actions do not require a certificate to be selected" separator
> and just sort within the separate bullet lists (not much won)
> - transform the separator into a note ("This action does not require a
> certificate to be selected.") to be appended to the respective button names
> (better, quite a bit of overhead)
> - add an asterisk (*) behind the respective button names and repeat that sign
> at the beginning of the separator which will not separate anymore but just
> explain (IMO best. Do we use that kind of "footnoting" somewhere else in Help?)

The description of the button functionality should clarify the context (selected). And I think you already have it there: "Display detailed information about the selected certificates" etc - it should be clear that we're talking about selected certificates.

The only thing that could be odd is that it looks like it assumes that multiple certificates are selected (maybe we could have "selected certificate(s)"?).

When it comes to importing, I think it's obvious that it doesn't involves any selection in the cert manager ;-)
Attached patch patch v3 (obsolete) — Splinter Review
Note: I think "To perform the following actions, select one or more certificates and click one of the following buttons" is enough to tell that multiple selections are possible and as you said the actions themselves describe whether they work on selections or not. That's why I just left it like that. Furthermore think our readers are intelligent enough to understand that "the selected certificates" includes single selections. ;-)
Attachment #378100 - Attachment is obsolete: true
Attachment #392779 - Flags: review?(stefanh)
Attachment #378100 - Flags: review?(stefanh)
(In reply to comment #14)
> Created an attachment (id=392779) [details]
> patch v3
> 
> Note: I think "To perform the following actions, select one or more
> certificates and click one of the following buttons" is enough to tell that
> multiple selections are possible and as you said the actions themselves
> describe whether they work on selections or not. That's why I just left it like
> that.

Yes, but as the actions themselves describe whether they work or not on selections you shouldn't need "select one or more certificates and click one of the following buttons" (and it isn't really correct anymore since we include the import button etc),
(whatever you say should include the possibility that a certificate doesn't need to be selected)
Attached patch patch v3a (obsolete) — Splinter Review
(In reply to comment #15)
> as the actions themselves describe whether they work or not on
> selections you shouldn't need "select one or more certificates and click one of
> the following buttons" (and it isn't really correct anymore since we include
> the import button etc),

Since I removed all other traces of selections in the context I think we should keep that part as a reminder that selecting certificates is the key to enable all buttons. I added "(or none for xxx)" where applicable, though ("or" since those buttons work with or without selection).

BTW: I also made the changes to Authorities I forgot in the last patch.
Attachment #392779 - Attachment is obsolete: true
Attachment #392795 - Flags: review?(stefanh)
Attachment #392779 - Flags: review?(stefanh)
I expect I'll be able to look at this the forthcoming week.
Comment on attachment 392795 [details] [diff] [review]
patch v3a

"To perform the following actions, select one or more certificates (or none
  for Backup All or Import) and click one of the following buttons:"

I still don't like this. I think we should re-write it to something in line with this (except for the Others section, of course):


"Use the following buttons to view and manage your certificates. Note that most actions will require that one or more certificates are selected:"
Attached patch patch v3b (obsolete) — Splinter Review
Attachment #392795 - Attachment is obsolete: true
Attachment #394705 - Flags: review?(stefanh)
Attachment #392795 - Flags: review?(stefanh)
Attached patch patch v4 (obsolete) — Splinter Review
Attachment #394705 - Attachment is obsolete: true
Attachment #394708 - Flags: review?(stefanh)
Attachment #394705 - Flags: review?(stefanh)
Attached patch patch v4aSplinter Review
Attachment #394708 - Attachment is obsolete: true
Attachment #394710 - Flags: review?(stefanh)
Attachment #394708 - Flags: review?(stefanh)
Attachment #394710 - Flags: review?(stefanh) → review+
http://hg.mozilla.org/comm-central/rev/511e4fffc2e8
Status: ASSIGNED → RESOLVED
Closed: 15 years ago
Resolution: --- → FIXED
Target Milestone: --- → seamonkey2.0b2
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Created:
Updated:
Size: