330858 - Document all preferences

Status: RESOLVED DUPLICATE of bug 178685

(Developer Documentation Graveyard :: General, enhancement)

Description

[David E. Ross]

User-Agent:       Mozilla/5.0 (Windows; U; Win98; en-US; rv:1.8.0.1) Gecko/20060130 SeaMonkey/1.0 Mnenhy/0.7.3.0
Build Identifier: Mozilla/5.0 (Windows; U; Win98; en-US; rv:1.8.0.1) Gecko/20060130 SeaMonkey/1.0 Mnenhy/0.7.3.0

Request that a user-oriented dictionary of all preferences be available.  This would show all preferences that can be set in SeaMonkey via about:config and all preferences available to Firefox, Thunderbird, and other Mozilla-based products.  For each preference, the meaning and possible settings would be indicated.  Also, the product applicability would be indicated (with versions when preference names, settings, or meanings change).  

Yes, I know I could dig into the source code to get this.  But I haven't written serious code in about 10 years.  And this is an unacceptable burden to knowledgeable users who are not programmers.  

In any case, a central preference dictionary might improve the quality of development of modules that share preferences or interface through them.  

Reproducible: Always

Steps to Reproduce:

Comment 1

[David E. Ross]

The Wiki at <http://kb.mozillazine.org/About:config_entries> is very good.  This should be rehosted in the Mozilla.org site.  

Comment 2

[Gordon]

Maybe the about:config page could include hyperlinks to the wiki entries for each config option, and/or fetch a brief summery of the parameter from the wiki via RSS.

Comment 3

[David E. Ross]

I like the idea of using a wiki for the dictionary because it facilitates updates from such projects as SeaMonkey, projects which do not have the same official level of support as do Firefox and Thunderbird.  

However, I don't think an automatic linkage to any Web page from an application is a good idea.  I've seen too many such applications where linked pages have moved (even to a different domain), leaving the links useless in older (but still workable) versions of the application.  

Comment 4

[Arivald]

"mozilla.org" seems to be stable domain.

In case when it changes directory structure, there may be some mechanism to resolve this kind of problems. For example, at start program will download (or at least check checksum and download changes only) file "http://mozilla.org/RemoteHelpConfig.xml", and entries in file will allow any mozilla program to find correct links, regardless of program version.

And, as i check, Thunderbird 2.0 already download its "homepage" ("Welcome in Thunderbird!" page, displayed at start of program). It works fast and reliable.
So i think externaly linked help is good idea.

But i have another one, maybe better: Mozilla-based program installation package should contain at least base help files, and update them when user requests some help. If there is connection to internet, program will download (and display) new wersion from net, else it will use cached copy.
This will have two advantages: help accesible off-line, and help will be most up-to-date as possible.

Of course, base mechanism for this feature should be first implemented in toolkit. 
Maybe even extension developers will use it...

Comment 5

[David Boswell]

The www.mozilla.org site should no longer host documentation.  If there is still a need for this it should be added to MDC.  Moving to Mozilla Developer Center product for discussion.

Comment 6

[Mike Shaver (:shaver -- probably not reading bugmail closely)]

Nope, this is a user doc -- not MDC, maybe SUMO?

Comment 7

[Chris Ilias [:cilias]]

This is a request for one document for three products. support.mozilla.com is Firefox-only. 

Reporter, either file a separate bug for each product, or pick one product. If it's SeaMonkey, move this bug to SeaMonkey:Help. If this is for Firefox, this is bug is fixed <http://support.mozilla.com/en-US/kb/Using+the+spell+checker>. (support.mozilla.com KB policy is not to point people to about:config unless for troubleshooting or if there's significant demand.)

Comment 8

[myles7897]

is this a dupe of Bug 428582?

Comment 9

[David E. Ross]

Unless there is a user interface to set each preference variable, this bug report remains a valid request.  Frankly, such user interfaces would be excellent since they would then provide any necessary housekeeping (e.g., the necessary setting of related preference variables).  

Bug #428582 is a duplicate of this one.  If either is to be closed, it should be that one so as not to obscure how long this capability has been requested.  

The suggestion to have separate dictionaries of preferences is not valid.  While there are significant differences between Firefox and Thunderbird, most (all?) Firefox preference variables are also found in SeaMonkey, Camino, and perhaps Minimo.  Also most (all?) Thunderbird preference variables are also found in SeaMonkey.  

A single dictionary of preferences would serve both the user world and the developer world.  If well-written, a user who is advised to set a preference variable would know the consequences of doing so and also know about other variables that must be set.  If maintained and current, a developer would know what variables are in use and how they are used, avoiding creating redundant variables.  

I don't really care where the dictionary is hosted as long as users (not just developers) can EASILY access it.

Comment 10

[Majken Connor [:Kensie]]

That's the thing though, it's not meant to be a user interface, which is why we don't have an article for it on SUMO.

Comment 11

[Chris Ilias [:cilias]]

Oh, okay. Sorry, I misunderstood. I thought you wanted a doc that outlined all about:config preferences for the spell-checker. :-)

In that case, yes this is a dupe of a wontfix.
See <http://groups.google.com/group/mozilla.support.planning/browse_frm/thread/5aeae98966c022c4> and <http://groups.google.com/group/mozilla.dev.apps.firefox/browse_frm/thread/457b9017eeddee26>.

If you want another project to attempt an about:config spec, re-open this and move it to the appropriate bugzilla product.

Comment 12

[David E. Ross]

Even today, a novice user was advised in a news.mozilla.org to go to about:config and alter a preference variable.  A subsequent reply in that thread suggested several variables.  Unless this kind of advise can be stopped, the information I request here has great value to users.  (And is there a dispute that it would also have greate value to developers?)  

I already have three different Web sites bookmarked with encyclopedias of preference variables, none of which addresses ALL the variables used by SeaMonkey (most of which are also used by Firefox) or Thunderbird.  

I have updated the Summary to change "Dictionary" to "Encyclopedia" the Product from "support.mozilla.com" to "mozilla.org".   

Note:  This is NOT about the about:config capability.  I generally set preference variables in user.js, where I can insert comments to remind myself why I am using a non-default setting for a variable.

Comment 14

[David E. Ross]

For some UNEXPLAINED REASON, this bug was changed back to support.mozilla.com, which then caused it to be closed as a duplicate of another support.mozilla.com bug, which in turn is marked closed as WONTFIX.  

In a well-run, long-term software development project, a list (dictionary, encyclopedia, database) of external variables is an absolute necessity.  (Preference variables are indeed external variables.)  Such a list is a part of the interface control documentation.  For current developers, this provides guidance as to what variables already exist, what they mean, and the consequences of changing that meaning.  This becomes even more important as responsibilities for various modules are reassigned to new developers.  If such a list does not exist, I don't know how major interface bugs can be avoided.  (NOTE:  This paragraph is based on my experience over 40+ years as a software engineer, during which I spent 10+ years also doing software configuration management.)  

If a list of ALL preference variables does exist, it should be made visible to users.  This is necessary not only for those instances where advice in the various news.mozilla.org newsgroups suggests that users change their preference variables.  It is also needed for extension developers and also for users of such extensions as PrefBar (which allows users to tailor their own buttons, checkboxes, etc to control preference variables).  

If this bug is again closed as WONTFIX (either explicitly or implicitly as a duplicate of another WONTFIX bug), please address the issues I raise in this comment.

Comment 15

[Majken Connor [:Kensie]]

As it was explained to us when we WONTFIXed this for SUMO, these prefs aren't intended for users to change.  The only time we're instructing them to do so is in situations where other things have changed them and people should change them back, or if they're the only alternative to a real usability issue (in this second case we recommend extensions wherever possible).

It was my understanding that these prefs exist for developers which would make a catalog of the prefs and what they do appropriate for developer documentation. I'm not sure if Shaver pointed to SUMO instead of MDC because you were requesting a user doc, or if he feels that it should be a user doc. We should probably get clarification on that before any other changes to the bug are made.

Comment 16

[David Tenser [:djst]]

A full reference of all prefs is definitely MDC material.

Comment 17

[Eric Shepherd [:sheppy]]

Renaming.

Comment 18

[David Tenser [:djst]]

(In reply to comment #16)
> A full reference of all prefs is definitely MDC material.

Just wanted to clarify since I realize I overruled Shaver's recommendation: Having a reference for all prefs on SUMO would not be ideal because it would expose a lot of stuff we don't want exposed to end-users. 

For developers, however, knowing what even the "unsupported" prefs do is probably helpful. So, while I don't think it should be on SUMO, I could see this being included on MDC.

Comment 19

[David E. Ross]

The descriptions of all preference variables should be made available to end users except for those specifically identified as potentially harmful.  That is, the public documentation should not be based on choosing which preferences to make public.  Instead, the default should be to make everything public except for a limited set of preferences that are explicitly chosen to be kept private.

Comment 21

[Mike Connor [:mconnor]]

I am on record as saying that documenting hidden preferences for end users is not something I want to see for Firefox.  By documenting these and providing that information to users, we are creating a future problem for ourselves.  i.e. an undocumented feature that goes away isn't a big deal.  A documented one is a much bigger deal, and we've burned a lot of cycles on making hidden prefs work, and its not really a winning play.

For developers, sure, for end users, absolutely not on my watch.