Add missing panel descriptions in the settings dialogs. #17701
Conversation
|
@heiko-folkerts-msg-david - have you seen #17160? There's some text there that might be good to use. Particularly for IME and review cursor |
There was a problem hiding this comment.
I have put some comments.
But my main feedback would be the following:
IMO, the description is not useful if it only lists the options available in the panel. It is useful if it synthesizes why the options available in one panel are there and not in another one.
- For the user, it should help understand the logic of the organization of the options in the various panels
- In addition, for developers, it also helps understand the organization of the options, especially, when they have to add a new option.
source/gui/settingsDialogs.py
Outdated
| panelDescription = _( | ||
| # Translators: This is a label appearing on the braille settings panel. | ||
| "Configures various settings for braille in and output." | ||
| " You can set which braille table to be used and other options.", |
There was a problem hiding this comment.
Why have you chosen to mention table explicitly and other options implicitly?
SaschaCowley
added
the
conceptApproved
|
I pushed new commits and did my best to integrate all review comments.
I also used some texts from the referenced PR.
|
See test results for failed build of commit 8b90e08c8e |
|
Sorry, but I don’t feel responsible for the exceeded build time of 60 minutes since I only added some strings.
|
| @@ -1644,6 +1657,10 @@ class VoiceSettingsPanel(AutoSettingsMixin, SettingsPanel): | |||
| # Translators: This is the label for the voice settings panel. | |||
| title = _("Voice") | |||
| helpId = "SpeechSettings" | |||
| panelDescription = _( | |||
| # Translators: This is a label appearing on the voice settings panel. | |||
| "Configures the voice settings for the selected speech synthesizer.", | |||
There was a problem hiding this comment.
Does this information really show up somewhere? I cannot see it nor hear it.
There was a problem hiding this comment.
Sorry, I am not convinced by this work.
First, I have noted the following issues:
- some descriptions can be heard but are not visible (visually); please sighted people, double check, I can have missed something...
- also adding a descriptions at the beginning of each panel makes the navigation more verbose, e.g.:
- when you press Tab from the category list to enter the panel, you need to hear the full panel description before hearing the first option
- when you press control+tab to switch panel, you hear the panel description before hearing the first option
I think that before accepting such a work to be begun, we have forgotten to think why it would be needed. After re-reading this PR and testing it, my opinion is that:
- the descriptions should be short or not present at all
- they should be present only if they really add an extra information, e.g. adding a description to the Audio panel is not needed because we already know which type of options are in this panel and what they are about...
To summarize, in addition to technical issues, the most important is that we should re-discuss when and why a description is needed or not.
| @@ -2494,6 +2530,10 @@ class BrowseModePanel(SettingsPanel): | |||
| # Translators: This is the label for the browse mode settings panel. | |||
| title = _("Browse Mode") | |||
| helpId = "BrowseModeSettings" | |||
| panelDescription = _( | |||
| # Translators: This is a label appearing on the browse mode settings panel. | |||
| "Configure how NVDA behaves when reading complex documents, such as web pages and emails.", | |||
There was a problem hiding this comment.
| "Configure how NVDA behaves when reading complex documents, such as web pages and emails.", | |
| "Configure how NVDA behaves when reading complex documents, such as web pages and e-mails.", |
There was a problem hiding this comment.
But actually, are e-mails in Thunderbird in browse mode?
| @@ -2995,6 +3035,10 @@ class DocumentNavigationPanel(SettingsPanel): | |||
| # Translators: This is the label for the document navigation settings panel. | |||
| title = _("Document Navigation") | |||
| helpId = "DocumentNavigation" | |||
| panelDescription = _( | |||
| # Translators: This is a label appearing on the document navigation settings panel. | |||
| "Configures options impacting how you navigate in a document with the cursor. ", | |||
There was a problem hiding this comment.
| "Configures options impacting how you navigate in a document with the cursor. ", | |
| "Configures options controlling how you navigate in a document with the cursor. ", |
| @@ -2995,6 +3035,10 @@ class DocumentNavigationPanel(SettingsPanel): | |||
| # Translators: This is the label for the document navigation settings panel. | |||
| title = _("Document Navigation") | |||
| helpId = "DocumentNavigation" | |||
| panelDescription = _( | |||
| # Translators: This is a label appearing on the document navigation settings panel. | |||
| "Configures options impacting how you navigate in a document with the cursor. ", | |||
There was a problem hiding this comment.
This text does not seem to be visible (visually).
| @@ -3028,6 +3072,10 @@ class AudioPanel(SettingsPanel): | |||
| # Translators: This is the label for the audio settings panel. | |||
| title = _("Audio") | |||
| helpId = "AudioSettings" | |||
| panelDescription = _( | |||
| # Translators: This is a label appearing on the audio settings panel. | |||
| "Configures the audio settings like volume and sound splitting.", | |||
There was a problem hiding this comment.
IMO, this description is not needed. It only adds more verbosity for no more useful information.
| @@ -3240,6 +3288,10 @@ class AddonStorePanel(SettingsPanel): | |||
| # Translators: This is the label for the addon navigation settings panel. | |||
| title = _("Add-on Store") | |||
| helpId = "AddonStoreSettings" | |||
| panelDescription = _( | |||
| # Translators: This is a label appearing on the addon store settings panel. | |||
| "Configures the Add-on Store, including how to handle updates. ", | |||
There was a problem hiding this comment.
This information is not visually visible. Moreover, is it really useful? It only adds verbosity.
|
Well,
this is really frustrating:
1. First this issue was marked as GoodFirstIssue and triaged, so I trusted that this one would be easy to implement and wanted.
2. Adding some strings seemed to be one of the most simple fixes one can do. It seems that it turns out otherwise.
3. Mixing all the reviews with an unknown PR to get the best descriptions really took me some time.
4. There were already some panel descriptions which I tried to imitate. So which direction are we going?
5. Even after many years of daily usage of NVDA I had no clear knowledge of every category. Ofcourse I know that “audio” may be related to something like volume, but if one doesn’t know about the possibility of sound splitting how will he or she find the option? So IMO the descriptions are needed to help users get started and find options they might need.
6. Sorry, I cannot tell anything about the visibility of the descriptions since I only set the panelDescription value. If they aren’t visible in some panels than this would mean a bug in the UI renderer.
|
|
@heiko-folkerts-msg-david, I understand your frustration and I am sorry for that. First, please take into account that I am not a member of NV Access, so keep in mind that my opinion may differ from NV Access' one. Regarding my feedback differing from what was written / agreed in the initial issue: Sometimes, it may happen that issue seem easy to fix, and when you try to fix it, something unexpected pops up and makes it more difficult. It also sometimes happens that implementing a solution allow people to better imagine te consequence of a design choice: personally, I had not realized before the impact of the excess of verbosity caused by long panel descriptions. It's just the life of software development. Apart from this, IMO, it's not a good idea to add descriptions that are not visually visible, even if the main user base of NVDA do not use the visual channel. I have double checked and only the descriptions you have added are not visible; the pre-existing ones (e.g. Document formatting settings, Vision) are visible. I have not investigated why this difference.
You also write:
Your feedback, as the one from other people, is interesting. Hence my question, which should have been asked before: What do we expect from these panel descriptions? And as a follow-up, other questions:
I'd ask NV Access (@seanbudd, @Qchristensen, @SaschaCowley) to think again to this and to report their opinion about this. At last, @heiko-folkerts-msg-david, do not feel discouraged with this. It may take more time and work than you had anticipated, but it's normal and it will be for you the opportunity to learn more things. |
seanbudd
added
blocked/needs-product-decision
|
Adding the descriptions invisible was never my goal. I’ll check whether I can find a cause for that and fix it. Otherwise I will file an issue for that.
Maybe it would help if people could request the description with a keystroke when in the settings dialog so that the user can decide on its own when to ask for help. E.g. pressing F1. Currently I only get a blank browser window when pressing f1.
What do you all think of that solution?
|
|
Given that only the descriptions you have added are not visible, we would generally expect this PR to add visible descriptions like the existing ones, rather than it be handled in a separate issue. We'll get back to you and Cyrille soon regarding verbosity and content of these descriptions. |
|
We are in favour of only adding panel descriptions for settings categories which are not intuitive - e.g. keep Review Cursor, Input Composition, Browse Mode and remove Speech, Mouse, etc |
|
Sounds good to me.
Mit freundlichen Grüßen
Dipl.-Inf. (FH) Heiko Folkerts
DevOps Engineer
msg for automotive gmbh
Mittelweg 7
38106 Braunschweig
Tel.: +49 89 96 101 15 10
Fax: +49 531 24 379-79
Mobil: +49 152 22641316
E-Mail: ***@***.***
https://www.msg.group<https://www.msg.group/de/branchen/automotive>
Sitz der Gesellschaft: 85737 Ismaning
Geschäftsführer: Martin Ober, Dr. Andreas Scholz
Handelsregister: Amtsgericht München, HRB 295920
Bitte beachten Sie, dass der Inhalt dieser E-Mail vertraulich zu behandeln ist. Sofern Sie nicht der beabsichtigte Adressat sind, dürfen wir Sie bitten, uns umgehend zu benachrichtigen und den Inhalt dieser E-Mail zu löschen.
[msg – creating value for automotive We lead the way in digital transformation.]
Von: Sean Budd ***@***.***>
Gesendet: Mittwoch, 16. April 2025 02:04
An: nvaccess/nvda ***@***.***>
Cc: Heiko Folkerts ***@***.***>; Mention ***@***.***>
Betreff: Re: [nvaccess/nvda] Add missing panel descriptions in the settings dialogs. (PR #17701)
Caution: This email originated from outside of the organization. Despite an upstream security check of attachments and links by Microsoft Defender for Office, a residual risk always remains. Only open attachments and links from known and trusted senders.
We are in favour of only adding panel descriptions for settings categories which are not intuitive - e.g. keep Review Cursor, Input Composition, Browse Mode and remove Speech, Mouse, etc
—
Reply to this email directly, view it on GitHub<#17701 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AHZOP6DWEW3ZENICVLYZWOL2ZWM5FAVCNFSM6AAAAABXGOO4COVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDQMBXHAYDQOBRGQ>.
You are receiving this because you were mentioned.Message ID: ***@***.***>
[Das Bild wurde vom Absender entfernt.]seanbudd left a comment (nvaccess/nvda#17701)<#17701 (comment)>
We are in favour of only adding panel descriptions for settings categories which are not intuitive - e.g. keep Review Cursor, Input Composition, Browse Mode and remove Speech, Mouse, etc
—
Reply to this email directly, view it on GitHub<#17701 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AHZOP6DWEW3ZENICVLYZWOL2ZWM5FAVCNFSM6AAAAABXGOO4COVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDQMBXHAYDQOBRGQ>.
You are receiving this because you were mentioned.Message ID: ***@***.***>
|
|
@heiko-folkerts-msg-david - do you still intend on doing this? |
seanbudd
removed
blocked
blocked/needs-product-decision
|
We will close this as abandoned if there's no response in 2 weeks |
|
Hello NVDA team,
after wondering about this a couple of weeks I agree that there would be no big benefit in adding those descrip
tions. They have to be added multiple time
s so that they show up in the dialog visually – that was the part I didn’t realize in my first pushes.
Unfortunately I am currently not able to finalize code due to famil
Y and working conditions.
So maybe it is best to drop the Idea or make clear when and why descriptions are needed in settings dialogs.
Best
Heiko
Mit freundlichen Grüßen
Dipl.-Inf. (FH) Heiko Folkerts
DevOps Engineer
msg for automotive gmbh
Mittelweg 7
38106 Braunschweig
Tel.: +49 89 96 101 15 10
Mobil: +49 152 22641316
E-Mail: ***@***.***
https://www.msg.group<https://www.msg.group/de/branchen/automotive>
Sitz der Gesellschaft: 85737 Ismaning
Geschäftsführer: Martin Ober, Dr. Andreas Scholz
Handelsregister: Amtsgericht München, HRB 295920
Bitte beachten Sie, dass der Inhalt dieser E-Mail vertraulich zu behandeln ist. Sofern Sie nicht der beabsichtigte Adressat sind, dürfen wir Sie bitten, uns umgehend zu benachrichtigen und den Inhalt dieser E-Mail zu löschen.
[msg – creating value for automotive We lead the way in digital transformation.]
Von: Sean Budd ***@***.***>
Gesendet: Dienstag, 10. Juni 2025 02:28
An: nvaccess/nvda ***@***.***>
Cc: Heiko Folkerts ***@***.***>; Mention ***@***.***>
Betreff: Re: [nvaccess/nvda] Add missing panel descriptions in the settings dialogs. (PR #17701)
Caution: This email originated from outside of the organization. Despite an upstream security check of attachments and links by Microsoft Defender for Office, a residual risk always remains. Only open attachments and links from known and trusted senders.
[Das Bild wurde vom Absender entfernt.]seanbudd left a comment (nvaccess/nvda#17701)<#17701 (comment)>
We will close this as abandoned if there's no response in 2 weeks
—
Reply to this email directly, view it on GitHub<#17701 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AHZOP6BZYTM6QW3ED7B4GSD3CYRCNAVCNFSM6AAAAABXGOO4COVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSNJXGM3DGNRTGY>.
You are receiving this because you were mentioned.Message ID: ***@***.***>
|
|
No problem, thanks for your efforts. I will close this and someone else can consider picking up the work. |
seanbudd
added
the
Abandoned
Link to issue number:
Fixes #13568
Summary of the issue:
More config dialogs in NVDA settings should have descriptive text
Description of user facing changes
Added description for all classes derived from SettingsPanel so that all settings categories now have descriptions when tabbing into them.
Description of development approach
Copying the pattern description found for the object presentation category
Testing strategy:
Tested that the descriptions are spoken when running NVDA from source.
Known issues with pull request:
None. Did my best to write good english but it is not my mothers tongue.
Code Review Checklist:
@coderabbitai summary