Extend context help capability to add-ons

CyrilleB79 commented 3 years ago

Is your feature request related to a problem? Please describe.

Context help has been introduced in NVDA 2020.4 and allows to press F1 to get help in setting dialogs. It is very useful for core features of NVDA. However the same experience is missing in setting dialogs or panels created by the add-ons.

Describe the solution you'd like

Give an integrated and common possibility for add-on developpers to open the add-on documentation from its settings dialog or panel by pressing F1. The add-on documentation that is targeted is the one at the standard location in add-ons i.e.: NVDAConfigFolder\addons\addonName\doc\langCode\readme.html Optional (to be investigated): allow to put anchors in the add-on doc to jump to specific paragraphs corresponding to each wx control.

Describe alternatives you've considered

It's probably doable for each add-on author to implement it binding wx.EVT_HELP in order to open the doc when F1 is pressed. However defining a common framework in NVDA core has various advantage:

rationalize and factorise code that should else be defined in each add-on
encourage the use of this feature for add-on authors by advertising that a new feature is available in core for them
make implementation more easy for them since they would have only to define helpId in their dialogs/panels
This capability could also be documented / advertised in the documentation of the add-on template.

Additional context

Note

This feature request is about extending the existing context help design in add-on dialogs / panels. For a more general discussion about the whole context help (re)design including NVDA and add-ons, please see #2699.

josephsl commented 3 years ago

Hi, actually, I’d rather see context-sensitive help redesigned somehow to not rely on user guides and add-on readme content due to the current state of add-ons documentation (readme files are meant to provide high-level overview unless the overall attitude toward documentation authoring changes from within the community). Thanks.

nvdaes commented 3 years ago

Í support Cyrilles"s idea and, in pact, I wanted this peature to be implemented. Documentation may have furter requirements or recommendations to do this, in particular taking account that it"s translated converting markdown to po files, something, for now, not applied to de user guide. But for me this would be a good feature.

feerrenrut commented 3 years ago

One thing missing from the description of this issue that really ought to be pointed out explicitly: "the addon will need to have it's own separate help file, the addon will need to be able to give the path to this help file."

@josephsl I'm not really sure what you mean, but it sounds like a different issue. Please create one to expand on it.

josephsl commented 3 years ago

Hi, I guess a more recent discussion of #2699 is what I’m truly after, because as of now, only NVDA’s interface can include context-sensitive help, including GUI’s from add-ons. When I and some others talk about context-sensitive help, we mean contexts as in overlay classes also, not just NVDA and add-on GUI. I believe there was a discussion about an UX overhaul of context-sensitive help feature to use a browsable message instead of opening user guide sections inside a web browser, which comes closest to the vision I had when I created Control Usage Assistant in early 2013 and led the discussion on the mentioned issue (I had a pull request for that UX for a time, knowing that the discussion would eventually pivot to this). I even once thought about emulating pressing F1 from Control Usage Assistant add-on if one is focused on an NVDA GUI, but quickly abandoned it after realizing that a much better GUI help UX might be something to think about for long term. As for attitudes toward documentation on add-ons community, I think that’s something the add-ons community and NV Access should discuss at some point because it involves training authors to show more newbie-centric design in their docs and UI, which takes time to do given we will be navigating different languages and cultures (one aspect I do need to pass onto the add-ons community this summer is spending more time on designing better UI messages and documentation, which is a critical part of getting this issue resolution designed, implemented, tested, and adopted). Hope this clarifies things. Thanks.

cary-rowen commented 3 years ago

Hello,

If you check the "Report object descriptions" option in the "Object Presentation" of NVDA, you can report short and important contextual help information in the menu bar of MS Word. I think this is a very friendly UX design. Can this feature be applied to NVDA? I don't know if WXPython can do this?

Thanks

XLTechie commented 3 years ago

@josephsl, I believe you are talking about our discussion in #12362.

josephsl commented 3 years ago

Hi, ah yes, thanks for correcting me – I guess all the buzz about Windows 11 is not helping with my recollection skills at the moment…

XLTechie commented 3 years ago

Not a correction, just pointing to the one you mentioned sans number.

CyrilleB79 commented 3 years ago

Here are my answers to the various points raised: @feerrenrut wrote:

One thing missing from the description of this issue that really ought to be pointed out explicitly:

The goal is to use the standard doc of the add-on. I have updated the initial description to precise this point.

@josephsl wrote:

Hi, I guess a more recent discussion of #2699 is what I’m truly after, because as of now, only NVDA’s interface can include context-sensitive help, including GUI’s from add-ons.

The goal of this PR is to extend the current design to add-on documentation. Regarding a re-design of context help to target more than setting dialogs or panels, please discuss it in #2699. Of course, if #2699 is implemented in core taking into account add-ons, this issue can be closed. But I imagine that implementing this issue may be quite quickly integrated; on the contrary, #2699 may take more time to be discussed, designed and integrated. I'll update initial description to precise this more clearly.

As for attitudes toward documentation on add-ons community, I think that’s something the add-ons community and NV Access should discuss at some point because it involves training authors to show more newbie-centric design in their docs and UI, which takes time to do given we will be navigating different languages and cultures (one aspect I do need to pass onto the add-ons community this summer is spending more time on designing better UI messages and documentation, which is a critical part of getting this issue resolution designed, implemented, tested, and adopted).

I agree with you that some add-ons' documentation should be written better (as well as UI messages). IMO integrating the F1 capability in setting windows can help progressing towards this goal.

nvaccess / nvda