(English) Documentation Gives Wrong Instructions for Rule Creation

[XLTechie]

Add-on version: 2024.02.08
NVDA: 2024.1beta10
Firefox: 123.0

This seemed to be a very interesting add-on, and I was looking forward to trying it. However, in following the English documentation for first time use, I find that the instructions do not work in the interface.
Even doing what I think the instructions want but that isn't written there, the add-on itself doesn't work. See step 9 below for that part.

The instructions say to:

1. Create a module. This works.
2. Create a rule, by entering the name in the General section of the New rule option. This works.
3. Technical notes is not mentioned as a field, but that's probably okay.
4. In General, after entering the name, are we supposed to press OK, Apply, or not press any button? The Readme doesn't specify, so I assume neither should be pressed.
5. In switching to the Criteria category, is where the trouble begins. If you don't press the new button, there is an "Alternatives unknown" control. But that is fine, because the instructions instruct to press New.
6. When pressing New, we are immediately taken back to General, with the rule name we entered before erased. We must now enter a new rule name, starting over from the beginning.
7. In addition, the categories change from "General", "Criteria", "Actions", and "Properties". Instead, they become "General", "Criteria", and "Overrides". None of that is documented.
8. After entering the alternate rule name in General (or is this an inner rule?), we can then go to Criteria, and select options.
9. After choosing some Criteria--for example to move to the link title of an issue on a GitHub issues page--then choosing OK, then choosing a keyboard shortcut and maybe some other options, the OK/Apply buttons result in an error, and the dialog will not close.

ERROR - unhandled exception (06:09:12.595) - MainThread (1848):
Traceback (most recent call last):
  File "gui\settingsDialogs.pyc", line 735, in onApply
  File "C:\Users\luke\AppData\Roaming\nvda\addons\webAccess\globalPlugins\webAccess\gui\ruleEditor.py", line 943, in _doSave
    super(RuleEditorDialog, self)._doSave()
  File "gui\settingsDialogs.pyc", line 715, in _doSave
  File "gui\settingsDialogs.pyc", line 703, in _validateAllPanels
  File "C:\Users\luke\AppData\Roaming\nvda\addons\webAccess\globalPlugins\webAccess\gui\ruleEditor.py", line 286, in isValid
    if rule is not None and rule.name is not self.context.get("rule").name:
                                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'NoneType' object has no attribute 'name'

I can generate a more methodical and complete log if you can't easily reproduce this.

So this process seems convoluted and unnecessarily obscure. Why do we have to enter a rule name, switch to Criteria, press New, then start back at General and enter a rule name again? What happened to the first rule name we entered? Are there now two rules with similar (or the same?) names? Or is this a sub-rule inside the outer rule?

Obviously these instructions have not been updated, because they don't mention the "Technical Notes" fields, which appear in several places (twice in the second "General", for example), and there are fields such as "Help (Markdown)" in the module creation step, that are also not documented.

[AAClause]

Indeed, the documentation must be updated and there are several bugs.
Meanwhile, you can take a look at issue #7 for more info on rule editor. Most things are still relevant. However, we had to change some things. For instance, maintaining compatibility with older versions of NVDA is no longer a consideration.