Cc @nvdaes FYI since I guess you were the one to add the report language command.

the QSG does not indicate how to assign a gesture to a command, which makes mentioning unassigned commands useless in this guide.

I think we should solve this, rather than taking out useful information on potential commands. NVDA gestures are already fairly crowded.

if they are unassigned, they are probably not so common to deserve to be in the QSG

I think this might not always be true. As the keyboard gets crowded, there will be more and more useful gestures without a default

I agree with the intent here. Some points on the specifics (slightly out of order from the original):

1. Unassigned "Report Language": I agree this doesn't need to be in the QSG, but should it be covered elsewhere, perhaps somewhere near "12.1.2.13 Report language changes while reading"?

2. Adding info about what the synth settings ring is - good pickup, and the proposed change reads well.

3. The paragraph proposed for removal around the unassigned synth settings ring gestures - while this probably doesn't need to be in the QSG for the reasons given, the information is arguably useful and should perhaps be moved to basically exactly the same place, under the table of commands, in section "12.1.4 Synth Settings Ring" in the User Guide.

4. I agree that assigning a custom gesture probably doesn't need to be in the QSG - if there is a gesture we feel is important enough that a user should know it quite early in the use of NVDA, then it probably should have a gesture assigned to begin with. The exception to this would be for a user coming from another screen reader which had a command assigned which the user likes, which NVDA doesn't assign by default. In that case, however, having that command documented in places such as the Switching from Jaws to NVDA guide - I've linked there specifically to the quick navigation section, which mentions jumping between articles which is assigned in Jaws, and notes using the input gestures dialog to assign them if needed.

@Qchristensen thanks for the review.

1. Unassigned "Report Language": I agree this doesn't need to be in the QSG, but should it be covered elsewhere, perhaps somewhere near "12.1.2.13 Report language changes while reading"?

Sorry, my intent was to move it.
Since @nvdaes had put it next to report formatting and report link destination, I have sticked to this choice, which seems relevant. But put the command in the general guide rather than in the QSG.

3. The paragraph proposed for removal around the unassigned synth settings ring gestures - while this probably doesn't need to be in the QSG for the reasons given, the information is arguably useful and should perhaps be moved to basically exactly the same place, under the table of commands, in section "12.1.4 Synth Settings Ring" in the User Guide.

Sorry, I thought that it was covered in the general guide. I have added them with other synth settings ring commands, mentioning "none" to denote it's unassigned. That's what we tend to do recently, rather than writing text. This way, it also appears in the Commands Quick Reference.

4. I agree that assigning a custom gesture probably doesn't need to be in the QSG - if there is a gesture we feel is important enough that a user should know it quite early in the use of NVDA, then it probably should have a gesture assigned to begin with. The exception to this would be for a user coming from another screen reader which had a command assigned which the user likes, which NVDA doesn't assign by default. In that case, however, having that command documented in places such as the Switching from Jaws to NVDA guide - I've linked there specifically to the quick navigation section, which mentions jumping between articles which is assigned in Jaws, and notes using the input gestures dialog to assign them if needed.

OK. This should be studied case by case and should be documented in the "Moving from Jaws to NVDA" Guide rather than in the QSG.

@seanbudd wrote:

the QSG does not indicate how to assign a gesture to a command, which makes mentioning unassigned commands useless in this guide.

I think we should solve this, rather than taking out useful information on potential commands. NVDA gestures are already fairly crowded.

if they are unassigned, they are probably not so common to deserve to be in the QSG

I think this might not always be true. As the keyboard gets crowded, there will be more and more useful gestures without a default

@seanbudd did you realize that I am talking about the QSG (Quick Start Guide)? I am nnot talking about the User Guide in general. Just to be sure...

And re unassigned gestures, I agree that we should continue to cover them in the general User Guide, but not in the Quick Start Guide section.

Re assigning gestures, it's covered in paragraph "12.2.3. Input Gestures". IMO it does not need to be covered in the Quick Start Guide section too.

@CyrilleB79 - I did mean QSG, but Quentin disagrees - I will defer to him on this 😄

This PR is ready again.

There seems to be flaky Chrome tests. I have had to push an empty commit to re-run them and make them pass.