Skip to content

Fix up docs for 2026.1#19890

Merged
SaschaCowley merged 8 commits intobetafrom
2026.1docs
Apr 9, 2026
Merged

Fix up docs for 2026.1#19890
SaschaCowley merged 8 commits intobetafrom
2026.1docs

Conversation

@SaschaCowley
Copy link
Copy Markdown
Member

Link to issue number:

None

Summary of the issue:

The user guide and changelog for NVDA 2026.1 contain various typos, inconsistent capitalisation, broken anchors, incorrect key bindings, and minor wording issues that should be resolved before the translation freeze.

Description of user facing changes:

  • Fixed spelling and grammar throughout changes.md and userGuide.md (e.g. "recognising" → "recognizing", "aides" → "aids", "inside of" → "inside").
  • Corrected inconsistent capitalisation (e.g. "unicode" → "Unicode", "32bit" → "32-bit", "both" → "Both" at start of list items, consistent "Enhanced mode" / "Simple mode" / "Character mode").
  • Fixed incorrect key binding in the MathCAT navigation table: "Describe placemarker" now correctly reads control+shift+1 through control+shift+0 instead of control+shift+1 through shift+0.
  • Fixed a broken anchor {MathSpeechStyle} → {#MathSpeechStyle} and corrected cross-reference anchors (#reportSpellingErrors → #ReportSpellingErrors).
  • Added missing heading anchor {#MathTypicalUse} to the "Typical Use" section.
  • Removed the obsolete "AsCompound" MathCAT chemistry option and renamed "SpellOut" to "Spell it out" to match the current MathCAT UI.
  • Improved clarity of wording in the spelling/grammar error reporting settings, add-on copy to system configuration, and add-on store changelog sections.
  • Added missing issue reference (Add winBindings for crypt32 and replace raw ctypes calls. Move some structures into winBindings.crypt32 also. #18956) to a changelog entry.
  • Fixed minor formatting issues (missing space before backtick, extra space before comma).

Description of developer facing changes:

None

Description of development approach:

Instructed Claude Code to review user_docs/en/changes.md and user_docs/en/userGuide.md. Manually actioned its suggestions.

Testing strategy:

  • Manual review of the rendered documentation for correctness and consistency.
  • Verified that all cross-reference anchors resolve correctly.

Known issues with pull request:

None

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.

@SaschaCowley SaschaCowley added this to the 2026.1 milestone Apr 1, 2026
@SaschaCowley SaschaCowley marked this pull request as ready for review April 1, 2026 08:45
@SaschaCowley SaschaCowley requested review from a team as code owners April 1, 2026 08:45
Comment thread user_docs/en/userGuide.md Outdated
Copy link
Copy Markdown
Member

@seanbudd seanbudd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice catches

Comment thread user_docs/en/userGuide.md
Copy link
Copy Markdown
Member

@Qchristensen Qchristensen left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reads well, great work.

@CyrilleB79
Copy link
Copy Markdown
Contributor

Also, in MathCAT doc, we have various such tables:

| . {.hideHeaderRow} | . |
|---|---|
| Options | Checked, Unchecked |
| Default | Checked |

There are exceptions but most of the time, an option was rather Enabled / Disabled, so that's what need to be put in the table, not Checked / Unchecked, which is only the state of the corresponding checkbox.

Could we still change that?
I think this had already been reported when MathCAT has been introduced, but do not know where exactly.

Comment thread user_docs/en/userGuide.md Outdated
Comment thread user_docs/en/userGuide.md Outdated
@SaschaCowley SaschaCowley marked this pull request as draft April 7, 2026 02:21
@SaschaCowley
Copy link
Copy Markdown
Member Author

@CyrilleB79

Also, in MathCAT doc, we have various such tables:

| . {.hideHeaderRow} | . |
|---|---|
| Options | Checked, Unchecked |
| Default | Checked |

There are exceptions but most of the time, an option was rather Enabled / Disabled, so that's what need to be put in the table, not Checked / Unchecked, which is only the state of the corresponding checkbox.

I'm not sure what you mean. Would you prefer these tables be written as

| . {.hideHeaderRow} | . |
|---|---|
| Options | nabled, isabled |
| Default | Enabled |

To the best of my knowledge, the MathCAT section is the only part of the user guide that actually has these checkboxes for tables, so I'm not sure there is precedent either way. Personally I think checked and unchecked make more sense for these tables, but I don't mind either way.

@SaschaCowley SaschaCowley marked this pull request as ready for review April 7, 2026 02:47
Comment thread user_docs/en/changes.md Outdated
Comment thread user_docs/en/changes.md
Comment thread user_docs/en/changes.md
Comment thread user_docs/en/changes.md Outdated
Comment thread user_docs/en/changes.md
SaschaCowley and others added 3 commits April 9, 2026 17:21
Co-authored-by: Cyrille Bougot <cyrille.bougot2@laposte.net>
Co-authored-by: Luke Davis <8139760+XLTechie@users.noreply.github.com>
@SaschaCowley SaschaCowley enabled auto-merge (squash) April 9, 2026 07:29
@SaschaCowley SaschaCowley merged commit 0040ff9 into beta Apr 9, 2026
73 of 75 checks passed
@SaschaCowley SaschaCowley deleted the 2026.1docs branch April 9, 2026 08:14
Comment thread user_docs/en/userGuide.md
@@ -1233,7 +1233,7 @@
Below is a summary of the most useful commands for those wanting to quickly get started with navigating mathematical content.

* Use the arrow keys to move left/right or up/down a mathematical structure (e.g. into/out of a fraction).
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this say "in" a structure?

Suggested change
* Use the arrow keys to move left/right or up/down a mathematical structure (e.g. into/out of a fraction).
* Use the arrow keys to move left, right, up or down in a mathematical structure (e.g. into/out of a fraction).

Comment thread user_docs/en/userGuide.md
Comment on lines +1236 to 1239
* If inside a table, `control+arrow` keys will move by cell.
* `home` / `end` moves to the start/end of the expression.
* `space` reads your current position.
* `shift+upArrow` / `shift+downArrow` will change the mode of navigation, which will be discussed in more detail in the following section.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if we're trying to keep this section less formal for a reason. But if not:

Suggested change
* If inside a table, `control+arrow` keys will move by cell.
* `home` / `end` moves to the start/end of the expression.
* `space` reads your current position.
* `shift+upArrow` / `shift+downArrow` will change the mode of navigation, which will be discussed in more detail in the following section.
* If inside a table, `Control+arrow` keys will move by cell.
* `home` or `end` keys will move to the start or end of an expression, respectively.
* `space` reads your current position.
* `shift+upArrow` and `shift+downArrow` will change the mode of navigation, which will be discussed in the next section.

I have left the keys lower cased, contrary to the Microsoft standard, since that's common in the UG.
Removed the "in more detail" from the last item, because it hasn't been discussed in any detail so far.

Comment thread user_docs/en/userGuide.md

MathCAT's navigation is the same in Microsoft Word and in a web browser.

While navigating an expression, `control+c` copies the math content of the current node in NVDA.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could this line be clarified? The "in NVDA" here, reads strangely to me. Presumably it's the "node in NVDA", is it actually a virtualized node in NVDA, as the user understands it?
Would it be better to say "the current formula node" or some such, and leave off the "in NVDA"?
Not leaving a suggestion, because this sounds odd, but I'm not sure what's better. I'm not someone who works with formal math a lot.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the concept of "node" has not been introduced anywhere previously and is not something meant to be known by end users.

@CyrilleB79
Copy link
Copy Markdown
Contributor

I'm not sure what you mean. Would you prefer these tables be written as

| . {.hideHeaderRow} | . |
|---|---|
| Options | nabled, isabled |
| Default | Enabled |

Yes.

To the best of my knowledge, the MathCAT section is the only part of the user guide that actually has these checkboxes for tables, so I'm not sure there is precedent either way.

Yes, putting such tables in the UG is quite recent, especially for checkboxes, but there are at least 2 existing examples:

  • Delayed descriptions for characters on cursor movement (in Speech settings)
  • Volume of NVDA sounds follows voice volume (in Audio settings)

Personally I think checked and unchecked make more sense for these tables, but I don't mind either way.

On the contrary, I think that enabled/disabled makes more sense. Not yet very sure why and I have no time these days to think deeper to this. But in a first thought, I'd say that Enabled/Disabled can be defined as soon as the option name is defined, what is always the case since the header of the section is the option's name. On the other hand, checked/unchecked can only exist as the state of a checkbox, so if we have explicitly mentioned such checkbox before. Are we sure we have mentioned a checkbox in all paragraph?
More generally, I prefer when the multiple choices of an option are described in such paragraphs, no how they are presented in the GUI (i.e. check-boxes, combo-boxes, etc.)

@CyrilleB79
Copy link
Copy Markdown
Contributor

@SaschaCowley, @seanbudd, @XLTechie's comments have been posted little time after this PR was merged, I imagine they have actually been written in parallel while you were merging. But they are valuable IMO and would have deserved a subsequent quick PR before beta11 and translation freeze.

Also my comment mentioning the inconsistency regarding checkbox option tables between MathCAT and the rest of the User Guide (#19890 (comment)) had been posted one week before this PR was merged. True that me comment confirming this inconsistency with evidences has been posted the same day after the merge (#19890 (comment)) has been posted after the merge of this PR (the same day) since I had no access to a computer before. But it would have been easy to check yourself and / or to fix this inconsistency in a subsequent PR before the translation freeze.

Would you still accept a PR with all these changes since we are at the very beginning of the freeze? Or better, do and review this PR yourself to go faster (because being at opposite sides of the earth, we often lose one ore more days when communicating together!)
Thanks.

@SaschaCowley
Copy link
Copy Markdown
Member Author

@CyrilleB79 I don't think any of the issues identified are sufficient to justify violating the string freeze. Feel free to open an issue/PR to fix the remaining issues in 2026.2

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants