Confusing description of options in user guide

[CyrilleB79]

Since recently, the user guide uses definition lists to describe new options, more specifically their default and possible values. I feel it confusing.

Steps to reproduce:

• Go to Delayed descriptions for characters on cursor movement paragraph in the User Guide.
• Read and navigate with down arrow or "I" key

Actual behavior:

• List is reported with 4 item but navigating with I allows to get only two items
• On the contrary to standard lists (<ul>), definition list do not present bullets for each item (<dt> or maybe <dl>); thus it's not easy to understand where the term is and where the description is.
• More generally, the semantic between terms and their definition / description is not present.

Expected behavior:

The issue with definition list is discussed in #3858. It does not seem that its resolution is a priority and even if it was, the solution proposed in #3858 would not lead to a satisfactory UX when reading the User Guide. Indeed, it is written:

NVDA should announce "Term" for each dt element.

This would lead to hearing "term option" and "term default" which seems strange. "term" for definition lists, but not for description list.

Since I do not expect #3858 to be resolved soon, I suggest to avoid using definition list in the User Guide. Instead, we may use tables or normal lists.

NVDA logs, crash dumps and other attachments:

N/A

System configuration

NVDA installed/portable/running from source:

N/A

NVDA version:

2022.3

Windows version:

N/A

Name and version of other software in use when reproducing the issue:

N/A

Other information about your system:

N/A

Other questions

Does the issue still occur after restarting your computer?

N/A

Have you tried any other versions of NVDA? If so, please report their behaviors.

Not looked at.

If NVDA add-ons are disabled, is your problem still occurring?

N/A

Does the issue still occur after you run the COM Registration Fixing Tool in NVDA's tools menu?

N/A

[CyrilleB79]

Cc @Qchristensen

[Brian1Gaff]

Normal lists would be far more useful for new users I feel. Brian

…

-- ***@***.*** Sent via blueyonder.(Virgin media) Please address personal E-mail to:- ***@***.***, putting 'Brian Gaff' in the display name field. ----- Original Message ----- From: "Cyrille Bougot" ***@***.***> To: "nvaccess/nvda" ***@***.***> Cc: "Subscribed" ***@***.***> Sent: Wednesday, October 12, 2022 10:26 AM Subject: [nvaccess/nvda] Confusing description of options in user guide (Issue #14240)

Since recently, the user guide uses definition lists to describe new options, more specifically their default and possible values. I feel it confusing. ### Steps to reproduce: * Go to [Delayed descriptions for characters on cursor movement](https://www.nvaccess.org/files/nvda/documentation/userGuide.html#delayedCharacterDescriptions) paragraph in the User Guide. * Read and navigate with down arrow or "I" key ### Actual behavior: * List is reported with 4 item but navigating with I allows to get only two items * On the contrary to standard lists (`<ul>`), definition list do not present bullets for each item (`<dt>` or maybe `<dl>`); thus it's not easy to understand where the term is and where the description is. * More generally, the semantic between terms and their definition / description is not present. ### Expected behavior: The issue with definition list is discussed in #3858. It does not seem that its resolution is a priority and even if it was, the solution proposed in #3858 would not lead to a satisfactory UX when reading the User Guide. Indeed, it is written: > NVDA should announce "Term" for each dt element. This would lead to hearing "term option" and "term default" which seems strange. "term" for definition lists, but not for description list. Since I do not expect #3858 to be resolved soon, I suggest to avoid using definition list in the User Guide. Instead, we may use tables or normal lists. ### NVDA logs, crash dumps and other attachments: N/A ### System configuration #### NVDA installed/portable/running from source: N/A #### NVDA version: 2022.3 #### Windows version: N/A #### Name and version of other software in use when reproducing the issue: N/A #### Other information about your system: N/A ### Other questions #### Does the issue still occur after restarting your computer? N/A #### Have you tried any other versions of NVDA? If so, please report their behaviors. Not looked at. #### If NVDA add-ons are disabled, is your problem still occurring? N/A #### Does the issue still occur after you run the COM Registration Fixing Tool in NVDA's tools menu? N/A -- Reply to this email directly or view it on GitHub: #14240 You are receiving this because you are subscribed to this thread. Message ID: ***@***.***>

[seanbudd]

We are going to prioritise #3858, however in the meantime we welcome adjusting the user guide to use tables instead of definition lists.