378641 - Firefox "Manual proxy configuration" documentation gives no useful information

Status: VERIFIED FIXED

(support.mozilla.org :: Knowledge Base Articles, task)

Description

[Dan Harkless]

User-Agent:       Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.8.1.3) Gecko/20070309 Firefox/2.0.0.3
Build Identifier: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.8.1.3) Gecko/20070309 Firefox/2.0.0.3

While trying to figure out whether the fact that I couldn't talk to an HTTP proxy over HTTPS was a Squid problem (http://www.squid-cache.org/bugs/show_bug.cgi?id=1937) or a Firefox problem (https://bugzilla.mozilla.org/show_bug.cgi?id=378637), I dutifully read the Help  on "Manual proxy configuration".  The documentation was completely useless, punting and saying to "Ask your system administrator" for the correct settings.  What if you effectively _are_ the system administrator?  It would be nice if there were some actual documentation available (even if if in the form of a link to an article on mozilla.org), e.g. explaining that setting "SSL Proxy" doesn't allow you to talk to said proxy over SSL.

Reproducible: Always

Comment 1

[Jeff Walden (gone starting June 8)]

With all due respect, if you've set up your own custom proxy, I think it's reasonable to expect you should be capable of figuring out how to use it in Firefox.  If you're using some, e.g.,  Norton-provided proxy, Norton should provide instructions on its configuration in Firefox.  If you're in a business setting, the site admin should know the settings and be able to provide them.

Regarding this particular question, is it really that unclear, given that there are HTTP, FTP, SSL, Gopher, and SOCKS proxy options?  Without much thought on the matter I don't believe it is, but I'm open to arguments otherwise.

Built-in help docs are intentionally limited to try and address basic usage questions, not address problems which may require in-depth knowledge.  Firefox Help tries to hit 90% of uses and leave the remaining 10% to online resources run by Mozilla or by volunteers.  I appreciate help trying to make any of the help docs clearer, but I don't want to be documenting things most users will never use or which are better left to a sysadmin's experience.  There are too many generally  useful things that need docs more than proxy settings to justify spending a lot of time on good explanations here.

Comment 2

[Dan Harkless]

And indeed I was able to figure it out, but I would have been able to do so more quickly and perhaps without going down the path of thinking it was a Squid issue if Firefox documented its proxy options.  I'm of the school of thought that software should never have option settings (available via the normal UI) that have no documentation.  If it's a question of not wanting to bother the 90% of users that won't need to know something, the more detailed information can always be on a separate linked help page (or even a linked website page with a persistent URL).  But if it's an issue of a limited amount of time to spend documenting, and other areas that need it more, I understand.

Comment 3

[Samuel Sidler (old account; do not CC)]

For the record, the text of the current information in help is as follows:

  Manual proxy configuration

  Choose this if you don't have a proxy location (URL). Ask your
  system administrator for the names and port numbers of the servers
  running proxy software for each network service and enter the
  information in the appropriate fields.

I think this is something that should get covered as part of a knowledge base which will be the Firefox 3 help system. I'm going to confirm this bug to look at (and since it's a valid request to improve our help docs). I'm moving it to "enhancement" severity, however.

Comment 4

[Steffen Wilberg]

Moving over to sumo.

Comment 5

[benc]

-> me.

Comment 6

[benc]

Dan:

You comment is understandable, because historically, the description comes from Netscape, which controlled the client and the server (Netscape Proxy 2&3). So, there was a general understanding that customers had about how to make this work.

There hasn't been a single, end-to-end set of proxy docs that speaks to all relevant audiences. That is the not-so-secret agenda of my current contributions.

In the brave-new Web 2.0 world, there are a lot of proxies, and not all of them have the most complete documentation.

Specifically, The old "Secure" line in Communicator supported HTTPS and SNEWS, but then in Mozilla became "SSL Proxy" but only affected HTTPS (as far as I can tell from a code review).

---
I'm going to assume this bug is about the help text, i.e. end users. I'd also like to create an article for systems administrators (and possibly proxy-specific examples for popular proxies).

Here's the corrections I would suggest:

1- The radio buttons select a proxy "type", and I think each section for each type should have a single sentence on why they are selected, then a secondary paragraph that explains how to configure it.

Change:

Manual proxy configuration

  Choose this if you don't have a proxy location (URL).

to:

Manual proxy configuration

  Choose this if you have a list of one or more proxy servers.[new line]

2- Then an explanation of what to type:

Change:

Ask your system administrator for the names and port numbers of the servers
  running proxy software for each network service and enter the
  information in the appropriate fields.

to:

Ask your system administrator for the configuration information. Each proxy requires a hostname and a port number. 

If the same proxy name and port number are used for each field, you can check "Use this proxy server for all protocols".

If you want to bypass proxy for some hosts, use "no proxy for" [link to a page w/ more info]

---
(This field has a default value. Sometimes a system administrator will provide an entry, but other times, users will configure it themselves.).

Comment 7

[benc]

I created an SMO account for myself and submitted change #1...

Comment 8

[benc]

That change was accepted.

Comment 9

[benc]

Submitted change #2 to staging w/ some minor differences from above...

+ some info on "no proxy for".
- did not explain the socks version button.

It might need some formatting changes, but should be a significant improvement over the old version.

A couple other items, probably needs new bugs:

1- Still need an advanced proxy/sys admin version that explains the guts of this. I've stated something close on MDC, but it is turning into a dev/hacker oriented version.

2- Did not link the no proxy info into the no proxy doc, because it needs to be moved to MDC and cleaned up. Also, this feature is used by both sys-admins and power users. There is helper text and pretty good IE support via cut-and-paste and migration, so I didn't want to overload the end users.

Comment 10

[benc]

-> fixed. If someone wants more changes, please reopen.