AUD-460 Correction of documentation for configuring the email sending option

[TheNewCat777]

The Notifications documentation for Settings > Notifications was inaccurate and incomplete: SMTP
and Exchange Online setup were merged into a single confusing article, there was no mention of
national/sovereign cloud tenants, and the required Graph API permissions were listed without
explanation. This PR splits and corrects the documentation per AUD-460.

Changes

• Docs: settings/notifications/notifications.md - trimmed to a general overview (delivery
  method selection + Activity and Health Summary Email); no longer mixes SMTP/EXO steps together.
• Docs: settings/notifications/exchangeonline.md (new) - app registration steps; documents the
  "Tenant environment" selector (Default, US Government GCC, GCC High, DoD, China) with the
  correct login/Graph API endpoints per cloud, previously missing entirely; explains why both
  Mail.Send and Mail.ReadWrite application permissions are required (Mail.ReadWrite is only
  needed for the >3MB attachment draft/upload-session flow); keeps the optional
  application-access-policy restriction steps.
• Docs: settings/notifications/smtp.md (new) - full SMTP field reference table, aligned with
  the actual Settings > Notifications > Modify dialog, added the 1-65535 port validation range.
• Docs: settings/notifications/_category_.json (new) - groups the three pages under a
  non-clickable "Notifications" sidebar category so Exchange Online and SMTP show as sibling
  pages at the same nesting level.
• Docs: updated all internal/external links across 10.9 that pointed at the old flat
  settings/notifications.md path.

[github-actions]

Documentation PR Review

This PR splits the single settings/notifications.md page into a notifications/ category with a hub page plus dedicated Exchange Online and SMTP pages, and repoints all inbound links. I verified there are no remaining 10.9 references to the deleted path, and that finetune.md, the #restrict-application-access-optional anchor, and all new sibling links resolve.

Editorial Review

docs/auditor/10.9/admin/settings/notifications/notifications.md

• Clarity — Lines 16–17: "using either of two delivery methods, selected in the Method column" names a UI element without saying where it is. A reader arriving from a cross-link has no starting point. Suggested fix: "…using either of two delivery methods, selected in the Method column on the Settings > Notifications page:"
• Completeness — Line 29: "Navigate to the Summary email recipient and click Modify." doesn't say where to navigate from, so the procedure has no entry point. The UI element is also unbolded while Modify is bolded in the same sentence. Suggested fix: "In Settings > Notifications, go to Summary email recipient and click Modify."
• Structure — Line 25: the heading "Activity and Health Summary Email" doesn't cover the critical-event notifications the section body promises on line 27, and it drops that scope from the original page's "Summary Emails and Notifications about Critical Events". Suggested fix: retitle to "Summary Emails and Notifications About Critical Events" — or, if the two steps genuinely only configure the summary recipient, remove "and notifications about critical events" from line 27 instead.
• Clarity — Line 27: "Follow the steps to send summary emails and notifications about critical events." refers to "the steps" before they exist. Suggested fix: "To send summary emails and notifications about critical events, follow these steps:"
• Consistency — Line 37: "Health status tile" and "Health Status dashboard" are left unformatted while every other UI element on the page is bolded. Suggested fix: "…navigate to the Health status tile in the main window."
• Structure — Line 2: the page title is "Notifications" and it sits inside a category also labeled "Notifications" that _category_.json makes a non-clickable header, so the sidebar renders "Notifications > Notifications". Suggested fix: title the child page "Overview" (title: "Overview", # Overview), or give the category a "link": {"type": "doc", "id": "..."} so the hub page is the category itself.

docs/auditor/10.9/admin/settings/notifications/exchangeonline.md

• Clarity — Lines 21–22 contradict line 51. Line 21–22 tells the reader to save the Directory (tenant) ID because Netwrix Auditor needs it as Tenant name, but the field table on line 51 defines Tenant name as "Your Microsoft Entra primary domain name". Those are different values, and the reader can't tell which one to paste. Suggested fix: confirm what the field accepts, then make both places agree — e.g. line 21–22: "Save the Application (client) ID — you will need it as Application ID when configuring Netwrix Auditor. You will also need your Microsoft Entra primary domain name (for example, contoso.onmicrosoft.com) as Tenant name."
• Clarity — Lines 13, 27, and 42 use "Step 1/2/3" as H2 headings while each section restarts its own "Step 1 –" numbering inside. As a result, "saved in Step 1" (lines 52, 53) and "from Step 1" (line 129) are ambiguous, and are also inaccurate — those values are saved in Steps 3 and 4 of the first section. Suggested fix: drop the "Step N —" prefix from the H2s ("Register an Application", "Grant API Permissions", "Configure Notification Settings in Netwrix Auditor") and reference by action instead: "The Application (client) ID saved when you registered the application."
• Clarity — Lines 59–61 conflict with the note on lines 71–77. The lead-in states that a wrong selection "will cause authentication or sending to fail, because each cloud has its own login and Graph API endpoints", but the note then explains that US Government (GCC) uses the same endpoints as the commercial cloud, where the choice has no functional effect. Suggested fix: "Selecting an option that doesn't match your tenant's cloud can cause authentication or sending to fail, because most national clouds use dedicated login and Graph API endpoints."
• Completeness — Lines 24–25: the client secret step doesn't tell the reader that secrets expire, so notifications will silently start failing later with no explanation in this topic. Suggested fix: add an admonition after Step 4 — ":::note\nClient secrets expire. Record the expiration date and enter a new secret in Settings > Notifications before it expires, or email delivery will fail.\n:::"
• Completeness — Line 45: the configuration procedure ends without a way to confirm it worked, unlike the SMTP page, which points the reader at Send Test Email. Suggested fix: add a closing step — "Step 3 – Click Send Test Email to confirm the application can send mail, then click Save." (Adjust to the actual button available for the Exchange Online method.)
• Completeness — Lines 36–37: the table explains what each permission covers but never says which set to grant, leaving the reader to work out whether Mail.ReadWrite is optional for them. Suggested fix: add a lead-in after line 32 — "Grant both permissions unless you are certain report attachments will never exceed 3 MB, in which case Mail.Send alone is enough."
• Clarity — Line 103: "add the mailbox(es) the application is allowed to send from" uses a parenthetical plural. Suggested fix: "add each mailbox the application is allowed to send from".

docs/auditor/10.9/admin/settings/notifications/smtp.md

• Completeness — Lines 13–23: the settings table drops the Sender email (from) row that the original page documented, along with its caveats (it doesn't affect notifications sent to users' managers and administrators, and Exchange must support the option). If that field still appears in the UI, readers who see it now have no documentation for it. Suggested fix: confirm whether the field was removed in 10.9; if it still exists, restore the row.
• Clarity — Line 17: "The system will send a test message" — "the system" is vague where every other row names the product or the reader's action. Suggested fix: "Netwrix Auditor sends a test message to the specified email address and reports any problems it detects."
• Structure — Line 27: the page ends on an unrelated cross-link (Fine-Tune Your Plan) with no route back to the Notifications hub or across to the Exchange Online alternative, which is a dead end for a reader who picked the wrong method. Suggested fix: add a closing line — "To use modern authentication against Microsoft 365 instead, see Enable Notifications via Exchange Online."

docs/auditor/10.9/admin/monitoringplans/azurefiles.md

• Consistency — Line 26: the updated link uses the /docs/auditor/10.9/…/notifications.md form while the bullet directly above it (line 25) and the Next Steps links (lines 77–78) still use the /docs/auditor/10_9/… URL form without .md. Mixing both forms inside one list is inconsistent, and the 10_9 links bypass build-time link checking. Suggested fix: normalize the neighbors to the same form — [Audit database (SQL)](/docs/auditor/10.9/admin/settings/auditdatabase.md), [Configure reports](/docs/auditor/10.9/admin/reports/overview.md), [Set up alerts](/docs/auditor/10.9/admin/alertsettings/create.md).

docs/auditor/10.9/admin/healthstatus/summaryemail.md

• Consistency — Line 12: the longer link path pushes this line to roughly 130 characters, well past the ~100-character wrap the rest of the file uses. Suggested fix: reflow lines 11–13 so the sentence break falls near column 100.

docs/auditor/10.9/admin/monitoringplans/create.md

• Consistency — Line 141: same issue — the line now runs to about 134 characters against the file's ~100-character wrap. Suggested fix: reflow lines 140–142.

docs/auditor/10.9/admin/monitoringplans/activitysummaryemail.md

• No issues found.

docs/auditor/10.9/admin/navigation/recommendations.md

• No issues found.

docs/auditor/10.9/admin/healthstatus/dashboard/overview.md

• No issues found.

docs/auditor/10.9/admin/settings/overview.md

• No issues found.

docs/auditor/10.9/admin/settings/notifications.md

• Deleted; all 10.9 inbound links were repointed, and no stale references remain.

Summary

18 editorial suggestions across 7 files. The two highest-value items are the Tenant name contradiction in exchangeonline.md (lines 21–22 vs. 51), which will block a reader mid-setup, and the missing Sender email (from) row in smtp.md, which may be a content regression from the split. Vale and Dale issues are auto-fixed separately.

---

What to do next:

Comment @claude on this PR followed by your instructions to get help:

• @claude fix all issues — fix all editorial issues
• @claude help improve the flow of this document — get writing assistance
• @claude explain the voice issues — understand why something was flagged

You can ask Claude anything about the review or about Netwrix writing standards.

Automated fixes are only available for branches in this repository, not forks.

[github-actions]

Auto-Fix Summary

68 issues fixed, 14 skipped across 11 files

Category	Fixes
Contractions	4
Substitutions	1
FollowTheStepsTo (rewrite)	1
WeakLinkText (rewrite)	1
Dale: idioms	1
Dale: misplaced-modifiers	1
Dale: passive-voice	47
Dale: positional-references	3
Dale: wordiness	9

Skipped (needs manual review)	Reason
docs/auditor/10.9/admin/settings/notifications/exchangeonline.md:66 — Netwrix.FirstPersonPlural	False positive — 'US' is part of the Microsoft cloud environment name 'US Government (GCC)' in the tenant environment table, not the pronoun 'us'. Rewriting would break the product's option label.
docs/auditor/10.9/admin/settings/notifications/exchangeonline.md:67 — Netwrix.FirstPersonPlural	False positive — 'US' is part of the Microsoft cloud environment name 'US Government L4 (GCC High)' in the tenant environment table, not the pronoun 'us'.
docs/auditor/10.9/admin/settings/notifications/exchangeonline.md:68 — Netwrix.FirstPersonPlural	False positive — 'US' is part of the Microsoft cloud environment name 'US Government L5 (DoD)' in the tenant environment table, not the pronoun 'us'.
docs/auditor/10.9/admin/settings/notifications/exchangeonline.md:72 — Netwrix.FirstPersonPlural	False positive — 'US Government (GCC)' in the note refers to the Microsoft cloud environment option, not the pronoun 'us'.
docs/auditor/10.9/admin/settings/notifications.md:1 — Dale: n/a	file no longer exists — this PR split it into docs/auditor/10.9/admin/settings/notifications/{notifications,smtp,exchangeonline}.md
docs/auditor/10.9/admin/settings/notifications/exchangeonline.md:7 — Dale: n/a	heading text — not modified to avoid breaking anchor links
docs/auditor/10.9/admin/settings/notifications/exchangeonline.md:37 — Dale: wordiness	long Mail.ReadWrite justification sentence — condensing it risks dropping a required technical condition (draft/upload-session/delete sequence)
docs/auditor/10.9/admin/monitoringplans/azurefiles.md:26 — Dale: n/a	only the Notifications link path changed; no Dale violations found in the file
docs/auditor/10.9/admin/settings/overview.md:17 — Dale: n/a	only the Notifications link path changed; no Dale violations found in the file
docs/auditor/10.9/admin/healthstatus/dashboard/overview.md:9 — Dale: idioms	"at-a-glance view" is established technical usage in this product's UI descriptions; rewriting risks changing the described dashboard behavior
docs/auditor/10.9/admin/navigation/recommendations.md:100 — Dale: positional-references	"the Move to active link below the recommendation" describes a physical UI location, not a cross-reference to other documentation content
docs/auditor/10.9/admin/navigation/recommendations.md:77 — Dale: wordiness	long Logon Activity sentence enumerates specific audited event types; splitting it risks dropping or regrouping the listed logon categories
docs/auditor/10.9/admin/monitoringplans/create.md:102 — Dale: wordiness	gMSA/SSRS NOTE is wordy but the qualifier chain carries the technical limitation; condensing risks altering the stated constraint
docs/auditor/10.9/admin/monitoringplans/create.md:109 — Dale: passive-voice	"data collected from the data sources included in this monitoring plan" — reduced participles read naturally here and an active rewrite would need an actor the source doesn't specify

Ask @claude on this PR if you'd like an explanation of any fix.

[github-actions]

Code Review

Scope: correctness, routing, and config only — Vale/Dale and editorial review are handled by the other workflows.

This PR splits docs/auditor/10.9/admin/settings/notifications.md into a notifications/ category with three pages. The mechanics are mostly right, but two routing/navigation issues need attention.

1. New _category_.json is missing link — duplicated, unclickable sidebar entry

docs/auditor/10.9/admin/settings/notifications/_category_.json:

{
  "label": "Notifications",
  "position": 50,
  "collapsed": true,
  "collapsible": true
}

Every other category in this product sets a category link — 120 of the 121 _category_.json files under docs/auditor/10.9/ have a "link" block, and this new file is the sole exception. The sibling parent, docs/auditor/10.9/admin/settings/_category_.json, is the pattern:

"link": { "type": "doc", "id": "overview" }

Consequence: the sidebar renders Notifications as a non-clickable expand-only category whose first child is also labeled Notifications (from notifications.md, sidebar_position: 10). Readers get "Notifications -> Notifications," and clicking the category header does nothing but toggle.

Suggested fix:

{
  "label": "Notifications",
  "position": 50,
  "collapsed": true,
  "collapsible": true,
  "link": {
    "type": "doc",
    "id": "notifications"
  }
}

2. The old page URL now 404s, with no redirect

The published URL /docs/auditor/10_9/admin/settings/notifications and — because 10.9 is isLatest: true in src/config/products.js — the unversioned alias /docs/auditor/admin/settings/notifications both disappear. Content moved to .../settings/notifications/notifications.

plugin-client-redirects in docusaurus.config.js only maps base-product URLs to the latest version and generates unversioned aliases via createRedirects; there is no per-page redirect map, so nothing catches this move. Existing external links, bookmarks, and search-engine results for the notifications page will land on the 404 page.

Two ways to handle it, either is fine:

• Add slug: /admin/settings/notifications to the frontmatter of notifications/notifications.md. Combined with the link fix above, this restores the exact original URL as the category's landing page. Note that no other doc in this repo currently uses slug:, so it would be a new pattern here.
• Or add an explicit entry to the redirects array in docusaurus.config.js pointing the old path at the new one.

Verified clean

• No dangling links. All seven 10.9 files that referenced the deleted page were updated to /docs/auditor/10.9/admin/settings/notifications/notifications.md. A repo-wide search for admin/settings/notifications turns up no remaining references to the old 10.9 path in markdown, JS, JSON, YAML, or CSV. 10.7 and 10.8 still point at their own notifications.md, which is correct — versions are independent.
• Sidebar. sidebars/auditor/10.9.js is type: 'autogenerated', so no manual sidebar edit is needed and none is missing.
• Anchors. onBrokenAnchors is throw. Both in-page anchors in exchangeonline.md (#tenant-environment-options, #restrict-application-access-optional) resolve against real headings.
• MDX safety. Every { and < in the new files sits inside a code span or fenced block, and <your organization> is escaped — no MDX parse hazards.
• sidebar_position values. 10/20/30 within the new category, and position: 50 on the category matches the deleted file's old position, preserving its slot in the settings list.
• No security concerns. No secrets, no scripts, no workflow changes; the PowerShell samples use placeholder tokens.

I did not run a production build (no node_modules in this environment) — the above is static verification against the config and the repo's conventions.