NVDA settings label inconsistencies between NVDA user interface and the user guide

josephsl commented 1 month ago

Hi,

Stems from #5201:

Detailed description of the issue

Suppose a trainer is demonstrating NVDA settings while consulting the user guide. While looking at settings interface, the trainer does not find the option in the user guide but locates the description for a similar sounding option. For example, in general settings panel, the option to change NVDA's user interface language is labeled "NVDA language" whereas the user guide calls it "Language".

Why are the other templates not appropriate in this case?

This issue is about inconsistencies between the user interface and the user guide. This cannot be classified as a bug as it might be an oversight. This is not a feature request in a strict sense of the template as this issue is asking for consistent documentation.

Have you asked for advice on how to report this issue via a community discussion? If so, please link to the discussion

None (see #5201 as justification).

Steps to reproduce or illustrate the issue (if applicable)

Open the NVDA user guide to chapter 12 (configuring NVDA).
Walk through the general settings.
Stop at "Language" section.
Press Control+NVDA+G to open general settings panel.
Notice the label for the first option (NVDA language).

Expected outcome or behaviour (if applicable)

Option label should be consistent between the user interface (general settings panel) and documentation (user guide).

Screenshots, logs, and other attachments (if applicable)

None

System configuration or software environment (if applicable)

Windows 11 24H2 preview (build 26100.1150)

Additional information (if applicable)

Used as NVDA development workstation (local source code available)

Inconsistencies between the user interface and the user guide

Settings category	User interface	User guide
General	NVDA Language (requires restart)	Language
General	Save configuration when exiting NVDA	Save configuration on exit
General	Notify for pending update on startup	Notify for pending updates on startup
Speech	Automatic language switching (when supported)	Automatic Language switching
Speech	Automatic dialect switching (when supported)	Automatic Dialect switching
Audio	Audio output device	Output device
Audio	Sound split mode	Sound split
Audio	Sound split	Customizing Sound split modes
Audio	Time to keep audio device awake after speech (seconds)	Time to keep audio device awake after speech
Input composition	Always include short character description when announcing candidates	Always include short character descriptions for candidates
Browse mode	Number of lines per page	Maximum Lines Per Page
Browse mode	Use screen layout (when supported)	Use screen layout
Browse mode	Trap all non-command gestures from reaching the document	Trap non-command gestures from reaching the document
Document formatting	Report formatting changes after the cursor (can cause a lag)	Report formatting changes after the cursor
Advanced	Use enhanced event processing (requires restart)	Use enhanced event processing
Advanced	Speak passwords in all enhanced terminals (may improve performance)	Speak passwords in all enhanced terminals
Advanced	Report transparent color values	Report transparency for colors
Advanced	Use WASAPI for audio output (requires restart)	Use WASAPI for audio output
Advanced	Enabled logging categories	Debug logging categories
Advanced	Regular expression for text paragraph navigation	Regular expression for text paragraph quick navigation commands

The ones with parentheses might not be up for editing (if the proposal is accepted) as text in brackets serve to highlight the effect of changing settings.

Discussion points:

Work on capitalization (#5201): I would say yes unless people think they should be separate.
Which text should be used: I think the user interface text should be used unless people think user guide text is better for some.
Work on options with parentheses: perhaps not for this one but maybe in a separate proposal.
Create a note in the project docs about making the user interface and the user guide consistent: perhaps, perhaps not.

Thanks.

XLTechie commented 1 month ago

@josephsl IMO, in the following cases, the UG text should be preferred over the UI text:

Audio output device: the category is audio. Including the word is redundant.

Browse mode: maximum lines per page is more accurate.

Browse mode: Trap non-command gestures from reaching the document. "All" is just unnecessary verbosity here.

Document formatting: Report formatting changes after the cursor. The part about the lag is of dubious truth on even remotely modern systems. Do we have any statistics demonstrating this supposed lag? I have not ever observed it when testing this feature, across all kinds of hardware, in at least eight years. If it is as questionable as I think, better to touch on it in the guide, and leave it out of the UI and option title.

Advanced: Debug logging categories. Are those categories logged when not in debug loglevel? Do they serve any purpose other than for debugging?

CyrilleB79 commented 1 month ago

Agree with @XLTechie's remarks.

In addition, I'd say that "Sound split mode" could just be "Sound split". IMO "there is no need to speak about modes of everything. Thus "Modes available in the 'Cycle sound split mode' command" could just become "Values available in the 'Cycle sound split mode' command". On the opposite for example, "Speech mode" cannot just become "Speech" for example. Cc @mltony for opinion if you wish.

The same way, "Audio ducking mode" could just become "Audio ducking", with the appropriate values listed in the combo box.

At last, while at it, should we double check the consistency of all options regarding the final colon (:)?

gerald-hartig commented 1 month ago

@Qchristensen

nvaccess / nvda