Skip to content

Update Help menu to include more links - split out docs#15688

Merged
seanbudd merged 7 commits into
masterfrom
updateHelpMenu
Nov 2, 2023
Merged

Update Help menu to include more links - split out docs#15688
seanbudd merged 7 commits into
masterfrom
updateHelpMenu

Conversation

@seanbudd

@seanbudd seanbudd commented Oct 26, 2023

Copy link
Copy Markdown
Member

Link to issue number:

Fixes #14631

Summary of the issue:

  • Documentation (user guide, changes, licence, etc) could be moved out of the help menu to be better grouped.
  • The NVDA help menu would be improved with a link to NV Access's "Get help" web page, as well as the NV Access Shop for training materials.

Description of user facing changes

New menu structure, previously these were all under "Help"

  • Documentation
    • User Guide
    • Key commands
    • Changes
    • License
    • Contributors
  • Help
    • NV Access website
    • NV Access Get Help page
    • NV Access Shop page
    • Welcome dialog
    • Check for update
    • About dialog

Accelerator keys had to be updated due to the moving of items.

Description of development approach

  • New helper functions were created for each updated section of the NVDA menu.
  • The usage of https://nvda-project.org/ was updated to the current NV Access website URL, and the entry for the Menu item has changed from "NVDA website" to "NV Access website".
  • The donation URL was updated to use the https version of the NV Access website URL

Testing strategy:

Test opening menu items manually

Known issues with pull request:

Code Review Checklist:

  • Documentation:
    • Change log entry
    • User Documentation
    • Developer / Technical Documentation
    • Context sensitive help for GUI changes
  • Testing:
    • Unit tests
    • System (end to end) tests
    • Manual testing
  • UX of all users considered:
    • Speech
    • Braille
    • Low Vision
    • Different web browsers
    • Localization in other languages / culture than English
  • API is compatible with existing add-ons.
  • Security precautions taken.

@seanbudd seanbudd requested a review from a team as a code owner October 26, 2023 04:27
@lukaszgo1

Copy link
Copy Markdown
Contributor

Aside from the fact that changing accelerator keys would (as it always does) cause annoyance for users (but I assume you have considered that and decided that these improvements justify it), I'm not sure I understand the reasoning behind moving of the 'check for updates' item out of the help menu. Looking at other programs I have installed the only one in which ability to check for updates is not in the help menu is MS Office, though that is likely because it auto-updates in the background. In all other cases (Firefox, JAWS, Acrobat Reader, Notepad++, VS Code...) this option is in the help menu, so that seems to be standard placement. It is also worth pointing out, though this may may affect only more advanced users, that for try builds, source copies, etc. this option is hidden, so if i weren't following this thread, updated to the version with this change,pressed NVDA + N -> H -> C (as I've been doing for years to check for updates), and notice that the option is not there, it is likely I would try to debug why my update check stopped working, and don't think to look throughout the entire menu. If you want to group these options together it appears more logical to move "install pending update' to the help menu, rather than the other way around. Also has it been considered to make 'documentation' a sub menu of the help menu, instead of its own, independent menu?

@seanbudd

Copy link
Copy Markdown
Member Author

We'd like more feedback on these changes before making a decision and merging

@seanbudd

Copy link
Copy Markdown
Member Author

Also has it been considered to make 'documentation' a sub menu of the help menu, instead of its own, independent menu?

Depth is more annoying to navigate, and only 2 of the docs in the submenu are related to "help" (user guide, key commands).

@cary-rowen

Copy link
Copy Markdown
Contributor

I'm not a big fan of changing the entry for checking for updates and documentation, besides breaking the accelerator habit would be confusing, there are many external tutorials or add-on documentation that may also mention the path to these documents.

@XLTechie

XLTechie commented Oct 27, 2023 via email

Copy link
Copy Markdown
Collaborator

@XLTechie

XLTechie commented Oct 27, 2023 via email

Copy link
Copy Markdown
Collaborator

@seanbudd

Copy link
Copy Markdown
Member Author

Many applications include the Check for/Install updates option, at the top of their About dialog, with the version number. That doesn't mean we should, it is just one of the common placements. Others, as @lukaszgo1 said, put it in the Help menu if they have one. Rarely have I noticed it in the main Window, which for us would be on the main menu. Personally I prefer that it remain where it has traditionally been.

The main reason to move it is for discoverability and to keep it with the "install pending update" item. Moving the other item to the help menu would decrease the discoverability of pending updates. We can stick with convention but checking for an update doesn't really fit under "Help" logically.
I think being able to check for update from the about dialog as well would be a nice to have.

@lukaszgo1

Copy link
Copy Markdown
Contributor

The main reason to move it is for discoverability and to keep it with the "install pending update" item. Moving the other item to the help menu would decrease the discoverability of pending updates.

It may be more discoverable visually, but for blind users this does not really matter - they need to move through the entire menu to find it regardless in which one these options are placed. I would say the main way people install pending updates is either from the pending update reminder on startup, or from the exit dialog, though I don't have any scientific evidence to back this up.

@seanbudd

Copy link
Copy Markdown
Member Author

Considering it is safer to stick with convention for the check for update, that change has been reverted

@AppVeyorBot

Copy link
Copy Markdown

See test results for failed build of commit d4979a25c7

@seanbudd seanbudd requested a review from Qchristensen October 31, 2023 00:53
@cary-rowen

Copy link
Copy Markdown
Contributor

I think this PR was merged too early. He doesn’t seem to be hearing enough from the community. In my opinion, "documentation" also falls under the category of help.
Sorry, I don't see any obvious benefit to having Documents as a separate menu.

@CyrilleB79

Copy link
Copy Markdown
Contributor

I also comment a bit late.
I have no very strong impression about this change and will not fight in any direction to have it modified, i.e. I will not open a new issue or PR to optimize this.

Anyway here is my personal impression:
The documentation menu does not bring anything interesting. Specifically, in many applications, the help doc (user guide) can be found in the Help menu. I feel that separating Help and Documentation may lead to confusion, i.e. "I do not remember if User Guide is in Help or in Documentation".
Maybe the scope for splitting the help menu was to avoid a menu with too much items? In this case, a submenu "Useful links" under the Help menu can group all the links on NV Access website.
I agree that the User Guide should not be put in a 2nd sublevel menu; but for links on NV Access website, I think that it may be acceptable.

At last, I note that adding more items pointing on NV Access website may not be so interesting for non-English speaking users of NVDA; this issue was already present with the link on the main page of NV Access website, but adding these new links makes it more noticeable.

@codeofdusk

Copy link
Copy Markdown
Contributor

It looks like the "check for updates" reversion wasn't successful, and its placement in the root menu is confusing, misleading, and breaks years of muscle memory.

I like the proposal by @CyrilleB79 to restore the "documentation" items back to the help menu, and add a "useful links" (or similar) submenu.

@LeonarddeR

Copy link
Copy Markdown
Collaborator

Lets move the discussion to #15740. Comments on closed pull requests are easily missed.

seanbudd pushed a commit that referenced this pull request Nov 6, 2023
Close #15740

Summary of the issue:
#15688 moved “Check for update” to the NVDA main menu.

Description of user facing changes
The user can again use the “Check for update” option in the Help menu.
@CyrilleB79

Copy link
Copy Markdown
Contributor

Actually the discussion takes place in #15749.

seanbudd added a commit that referenced this pull request Nov 10, 2023
Fixes #15749
Partially reverts #15688

Summary of the issue:
There has been significant negative feedback to the creation of the documentation menu.
Instead items should be return to the help menu.
Given that there is now 11 items in the Help menu, more separators should be added.

Description of user facing changes
The new help menu structure is:

User Guide
Key commands
Changes
[separator]
NV Access website
NV Access Get Help page
NV Access Shop page
[separator]
License
Contributors
[separator]
Welcome dialog
Check for update
About dialog
Description of development approach
Move items back, remove internal variable menu_help which duplicated self.helpMenu
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add link to "Get Help" page to NVDA help menu

10 participants