Add documentation to advanced properties

[joshdoe]

There are so many properties, and so little documentation, that I believe we should have description or tooltip strings that can be registered with each property to describe what it does. This can be shown in the dialog either as a tooltip or shown in a text panel at the bottom or side. This string would also be used when searching. Looking at Preferences.java, instead of having 9 SortedMap's, it might be better for each property to have its own class, which would contain name, description, default, current value, etc. Of course we'd maintain backwards compatibility, so properties could be moved over piecemeal.

[stoecker]

Advanced preferences are no normal user preferences. In normal work they should not be modified. All important preferences can be found in preferences dialogs. Why should we complicate the preferences system with lots of additional information, which actually must not be used?

The currently form of advanced prefs are mainly an easy way to add hidden options to allow testing features which are not yet usuable or which for different reasons are not exposed to the user. Why should we document them and thus make them more offical?

[joshdoe]

There are more than just two kinds of users (beginners and developers), there's an intermediate to expert user which would like to tweak some of these preferences. Asking them to delve into the source code to figure out the meaning I think is asking a bit much. I can't see how documenting functionality can ever be a bad thing, and I don't think it has any bearing on whether it is official or not.

Looking at the preferences, there are a few that I change somewhat frequently, like simplify-way.max-error (perhaps this should be promoted to one of the dialogs...). Then there are some that I might change once in a long while, like selectaction.cycles.multiple.matches. Then there are others that I'll never touch, like cache.motd.html. Clearly we have preferences that are for beginners (most of which should end up in a dialog), some for intermediate/power/expert users, and others that are really just for developers. I believe it would be worthwhile to classify properties sufficiently so the intermediate user isn't bombarded with properties they would have no desire to change.

I believe providing documentation for the intermediate preferences (and classifying them as such) wouldn't interfere, but would rather expose users to useful functionality they didn't know existed (because it was hidden in the noise of the developer level preferences).

[skyper]

Replying to joshdoe:

There are more than just two kinds of users (beginners and developers), there's an intermediate to expert user which would like to tweak some of these preferences. Asking them to delve into the source code to figure out the meaning I think is asking a bit much. I can't see how documenting functionality can ever be a bad thing, and I don't think it has any bearing on whether it is official or not.

Looking at the preferences, there are a few that I change somewhat frequently, like simplify-way.max-error (perhaps this should be promoted to one of the dialogs...). Then there are some that I might change once in a long while, like selectaction.cycles.multiple.matches. Then there are others that I'll never touch, like cache.motd.html. Clearly we have preferences that are for beginners (most of which should end up in a dialog), some for intermediate/power/expert users, and others that are really just for developers. I believe it would be worthwhile to classify properties sufficiently so the intermediate user isn't bombarded with properties they would have no desire to change.

I believe providing documentation for the intermediate preferences (and classifying them as such) wouldn't interfere, but would rather expose users to useful functionality they didn't know existed (because it was hidden in the noise of the developer level preferences).

+1

I often find myself searching through tickets and announcements for settings I once had read somewhere but are not documented.

A better documentation is always an advantage !

I think it does not harm to mention the settings for power/expert user in a separate section or subpage of the action's wiki page.
Unexperienced user won't change anything as long as they do not get really annoyed/frustrated about something and you are warned about your changes.

Maybe a second backup of the preferences.xml is useful which is a bit longterm based. Yesterday my preferences.xml_bak was overriden just because I did download from some other area. A backup of preferences.xml of previous version or 24h upto weekly period would be useful.

20kb unzip won't harm and it could be hidden.

[stoecker]

Clearly we have preferences that are for beginners (most of which should end up in a dialog), some for intermediate/power/expert users, and others that are really just for developers. I believe it would be worthwhile to classify properties sufficiently so the intermediate user isn't bombarded with properties they would have no desire to change.

We have normal user, expert and advanced preferences. You now want to move the settings of the third group to the second one. This is a WONTFIX.

Hidden settings are hidden for a reason:

• most time they are untested and possibly broken
• they are experimental or feature tests
• they are internal data

When you think that a specific setting is important enough, that it should be available for advanced users, then create a ticket for it and if others agree it will be added to the preferences section.

A better documentation is always an advantage !

No. When we start to document stuff, we need to support it. We DONT WANT to support the hidden settings, as they are for several reasons not ready to make them proper settings. Otherwise they would be reachable normally.

Documenting also means that it gets much harder to change code. The hidden settings expose inner working mechanism. Proper settings are designed to be user centric. When code changes, the user interface for proper settings can be stable. To make hidden settings stable we would need to add more and more workarounds.

Also this is not possible from a technical point of view. Currently defining settings simply means a single call. This allows to implement code points where it is possible to tweak software easily. Sometimes these places are useful and get real settings. Making this system more complex only means that it will no longer be used.

Rather than documenting this I would turn of this advanced settings section totally and make it available with a special trick only. Have a look at "about:config" from firefox. Is this documented?