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]

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]

Documentation PR Review

This PR splits admin/settings/notifications.md into a three-page section and copy-edits eight linked pages. All 10.9 inbound links were updated correctly — no stale references to the old path remain in 10.9 (the remaining hits are in 10.7/10.8, which is correct since versions don't propagate). Review below covers added lines only.

Editorial Review

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

• Structure — Line 1: The filename deviates from the section-landing-page convention used throughout auditor/10.9, where every category index is overview.md (admin/settings/overview.md, admin/healthstatus/dashboard/overview.md, admin/monitoringplans/fileservers/overview.md). This one produces the stuttering URL /admin/settings/notifications/notifications. Suggested fix: rename to overview.md and update the eight inbound links in this PR to /docs/auditor/10.9/admin/settings/notifications/overview.md.
• Clarity — Line 17: "Select the method in the Method column" introduces the Method column without saying where it is. A reader arriving from create.md or recommendations.md doesn't know it's on the Notifications settings page. Suggested fix: "In Settings > Notifications, select the delivery method in the Method column:"
• Structure — Line 25: The heading "Activity and Health Summary Email" doesn't cover the section's own content — the body says "summary emails and notifications about critical events," and it covers two different email types. Suggested fix: "Summary Email and Critical Event Recipients".
• Structure — Lines 37–40: The Health Status dashboard paragraph sits inside the "Activity and Health Summary Email" section but is about the dashboard, not summary email recipients. The split also dropped the original transition ("For more information about product health, you can also navigate to..."), so it now reads as an orphaned statement after Step 2. Suggested fix: restore a transition sentence, or move it under its own ## Related Information heading.

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

• Clarity — Lines 21–22 vs. line 51: These two added passages contradict each other. Line 21 tells the reader to save the Directory (tenant) ID and enter it "as ... Tenant name"; line 51 defines Tenant name as "Your Microsoft Entra primary domain name." A tenant ID is a GUID; a primary domain name is contoso.onmicrosoft.com. A reader following Step 1 will enter the wrong value. Suggested fix: decide which the product accepts, then make both places agree and add an example — line 21: "Save the Application (client) ID — you will enter it as Application ID."; line 51: "Your Microsoft Entra tenant's primary domain name, for example contoso.onmicrosoft.com."
• Structure — Lines 13, 27, 42: The ## Step 1 — Register an Application / ## Step 2 / ## Step 3 headings each contain their own **Step 1 –**…**Step 4 –** markers, so the page has two independent "Step 1"s, "Step 2"s, and "Step 3"s. This is why the cross-references on lines 52, 53, and 129 are ambiguous. No other page in this doc set numbers its H2s. Suggested fix: drop the Step N — prefixes and use plain task headings — ## Register an Application, ## Grant API Permissions, ## Configure Notification Settings in Netwrix Auditor — keeping the **Step N –** markers inside each.
• Clarity — Lines 52, 53, 129: "saved in Step 1" and "from Step 1" are ambiguous given the duplicated numbering above — the values are actually saved in substeps 3 and 4 of the Register an Application section. Suggested fix: reference the section by name — "The Application (client) ID you saved when registering the application."
• Completeness — Lines 9–11: The page opens straight into registering an application with no prerequisites, but the procedure requires Microsoft Entra permissions to create app registrations and to grant admin consent (line 39), plus Exchange administrator rights for the optional policy (line 87). docs/CLAUDE.md specifies overview → prerequisites → procedures. Suggested fix: add a short ## Prerequisites list naming the required roles.
• Completeness — Lines 47–55: The procedure ends at "Fill in the following fields" with no step to save the settings and no way to confirm the configuration works. The SMTP page documents a Send Test Email button; this page doesn't say whether one exists for Exchange Online. Suggested fix: add a closing "Step 3 – Click Save." and a verification step or test-email instruction.
• Clarity — Line 36: "This covers every notification and report attachment up to 3 MB" leaves it unclear whether 3 MB is the attachment limit or the total message limit, and doesn't say the threshold is Netwrix Auditor's own switch-over point rather than a Graph limit. Suggested fix: "Mail.Send alone is sufficient for notifications and for reports whose attachments are 3 MB or smaller."
• Clarity — Lines 71–77: The note tells a GCC reader that the option "functionally ... behaves like Default" and to select it "only if you need to keep the setting explicit for your organization's records" — which raises the question of why the option exists without answering it, and invites a GCC admin to second-guess a correct selection. Suggested fix: state it plainly without the records rationale: "GCC tenants use the same login and Graph API endpoints as the commercial cloud. GCC High and DoD use dedicated *.us endpoints and China uses dedicated *.cn endpoints; for these, register the application in the corresponding Microsoft Entra environment."
• Consistency — Lines 114, 123–124, 129: Placeholders use curly braces ({ADMIN_EMAIL_ADDRESS_HERE}, {APPLICATION_ID_HERE}, {GROUP_EMAIL_ADDRESS_HERE}). docs/CLAUDE.md requires angle brackets for placeholders. Suggested fix: <admin-email-address>, <application-id>, <group-email-address>, updated in both code blocks and the line 129 prose.

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

• Completeness — Lines 13–23: The split dropped the Sender email (from) row that the deleted page documented. It covered a distinct field from Sender address, along with two caveats a reader needs: it doesn't affect notifications sent to users' managers and administrators, and Exchange must support the option. Neither this page nor exchangeonline.md accounts for it now. Suggested fix: restore the row, or if the field no longer exists in 10.9, confirm that and note the removal in the PR description.
• Completeness — Lines 25–27: The page ends at the Fine-Tune link. The deleted page closed with "After that, you can specify the recipient who will receive product activity and health summary emails," which pointed the reader to the recipient step. A reader who lands here from search never learns they still have to configure a recipient. Suggested fix: add a closing pointer to Notifications > Activity and Health Summary Email.
• Completeness — Lines 16, 18–20, 23: Four new factual claims appear that weren't in the source page: "Valid range is 1–65535", "Selected by default", and the three "Available only when ... is selected" dependency notes. These are the kind of specifics readers act on. Suggested fix: verify each against the 10.9 UI before merge, or drop the ones that can't be confirmed.

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

• Clarity — Line 64: Splitting the original scoped clause into a standalone sentence turned it into a blanket product statement: "Auditor doesn't provide reporting and alerting capabilities" now reads as though Auditor never provides them, when it only applies to the Long-Term Archive-only scenario. Suggested fix: "...you will only be able to receive activity summaries; in this scenario, Auditor doesn't provide reporting and alerting capabilities."
• Clarity — Line 124: Same problem in the Database Settings table. Suggested fix: "In this case, you will only be able to receive activity summaries, and Auditor doesn't provide reporting and alerting capabilities."
• Clarity — Lines 138–140: The added sentence broadens the wizard step to "the email settings it uses," but the very next sentence still says "Netwrix Auditor will automatically detect SMTP settings" and the section heading is still "SMTP Server Settings." Now that Notifications covers both SMTP and Exchange Online, a reader can't tell whether this wizard step handles Exchange Online. Suggested fix: pick one scope — either keep the section SMTP-only, or rename the heading to "Notification Settings" and say the step covers both delivery methods.
• Clarity — Line 48: "does the following:" no longer agrees with the list items that follow it ("Collect and pre-filter audit data", "Compress data and forward it") — the original read "do the following," which matched. Suggested fix: "does the following: - Collects and pre-filters audit data - Compresses data and forwards it to Auditor Server."

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

• Clarity — Line 25: "the events Netwrix Auditor wrote to the health log in the last 24 hours" uses past tense; docs/CLAUDE.md requires present tense throughout. Suggested fix: "Shows statistics on the events Netwrix Auditor writes to the health log in the last 24 hours."
• Completeness — Lines 36–37: "follow the steps in the [Notifications] topic" is now imprecise — after this PR, the Notifications page is a hub whose only steps are the summary-email recipient steps, and the delivery-method steps live on two child pages. The reader wants the recipient steps. Suggested fix: link to the specific section: "follow the steps in Activity and Health Summary Email."

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

• Clarity — Lines 14–15: "Notifications on user activity and event log collection (Event Log Collection Status) differ slightly" — differ from what? The rewrite preserved the dangling comparison. Suggested fix: "Notifications on user activity and event log collection (Event Log Collection Status) differ slightly from other Activity Summaries and don't list changes."
• Consistency — Lines 37–38: "the recipient you specified" is past tense and singular, while line 12 says "the recipients you specify." Suggested fix: "delivers a summary to the recipients you specify".

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

• Clarity — Line 17: "red means problems require your attention" breaks the parallelism with the green clause ("green means Auditor had no issues while auditing your IT infrastructure") and asserts that problems exist rather than that Auditor found some. Suggested fix: "red means Auditor found problems that require your attention."

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

• Clarity — Lines 114–115: "Select the recommendation types you want to display" misattributes the action — the reader selects types, Auditor displays them. Suggested fix: "Select the recommendation types you want Auditor to display."

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

• Consistency — Line 26: The updated link uses the correct repo form (/docs/auditor/10.9/...notifications.md), but the sibling bullets in the same list and in Next Steps still use the legacy underscore form without .md (/docs/auditor/10_9/admin/settings/auditdatabase on line 25, and lines 77–78). Since you're already touching this list, consider normalizing lines 25, 77, and 78 to match — the legacy form bypasses the build's broken-link checking.

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

• No issues found.

Additional note

The deleted page's URL, /docs/auditor/10_9/admin/settings/notifications, is currently live and will 404 after deploy for anyone holding a bookmark or external link. There's precedent for handling this in src/config/redirects/ (currently only accessanalyzer-26.1.js) — worth considering an auditor-10.9.js entry pointing the old path at the new hub.

Summary

25 editorial suggestions across 9 files (10 reviewed). The highest-priority items are the Tenant name contradiction in exchangeonline.md (lines 21–22 vs. 51), the dropped Sender email (from) field in smtp.md, the duplicated step numbering in exchangeonline.md, and the notifications/notifications.md filename convention. 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

22 issues fixed, 14 skipped across 11 files

Category	Fixes
OnceUsage (rewrite)	1
Dale: passive-voice	8
Dale: undefined-acronyms	1
Dale: wordiness	12

Skipped (needs manual review)	Reason
docs/auditor/10.9/admin/settings/notifications/exchangeonline.md:66 — Netwrix.FirstPersonPlural	False positive — 'US' is the country abbreviation in the Microsoft cloud environment name 'US Government (GCC)', a literal UI option value in a reference table, not the pronoun 'us'. Rewriting it would misname the product setting.
docs/auditor/10.9/admin/settings/notifications/exchangeonline.md:67 — Netwrix.FirstPersonPlural	False positive — 'US' is the country abbreviation in the Microsoft cloud environment name 'US Government L4 (GCC High)', a literal UI option value in a reference table, not the pronoun 'us'.
docs/auditor/10.9/admin/settings/notifications/exchangeonline.md:68 — Netwrix.FirstPersonPlural	False positive — 'US' is the country abbreviation in the Microsoft cloud environment name 'US Government L5 (DoD)', a literal UI option value in a reference 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 same Microsoft cloud environment option name, not the pronoun 'us'.
docs/auditor/10.9/admin/settings/notifications.md:0 — Dale: n/a	file does not exist in the working tree — replaced by docs/auditor/10.9/admin/settings/notifications/notifications.md in this branch
docs/auditor/10.9/admin/healthstatus/dashboard/overview.md:12 — Dale: idioms	"at-a-glance view" is established technical usage in dashboard documentation, not a culturally specific idiom; rewriting risks changing the author's meaning
docs/auditor/10.9/admin/healthstatus/dashboard/overview.md:23 — Dale: passive-voice	"all monitoring plans configured in Netwrix Auditor" is an adjectival past participle; dropping or rewording "configured" narrows the meaning
docs/auditor/10.9/admin/monitoringplans/activitysummaryemail.md:33 — Dale: passive-voice	"the computer where the user was logged on" describes a session state, not an action; the active rewrite ("where the user logged on") changes the meaning
docs/auditor/10.9/admin/monitoringplans/activitysummaryemail.md:26 — Dale: passive-voice	"the type of action performed on the object" — reduced relative clause in a terse table cell; no agent to promote
docs/auditor/10.9/admin/settings/notifications/exchangeonline.md:36 — Dale: passive-voice	"Required to send a message directly" — agentless table-cell fragment describing a permission requirement; no active subject available
docs/auditor/10.9/admin/settings/notifications/exchangeonline.md:37 — Dale: passive-voice	"Required only for attachments larger than 3 MB" — agentless table-cell fragment; no active subject available
docs/auditor/10.9/admin/settings/notifications/notifications.md:21 — Dale: undefined-acronyms	GCC, GCC High, and DoD are Microsoft cloud environment names shown verbatim in the product UI and expanded in the linked Exchange Online topic; spelling them out inside the parenthetical list would misname the UI options
docs/auditor/10.9/admin/navigation/recommendations.md:100 — Dale: positional-references	"below the recommendation" describes the physical position of a link within the product UI, not a cross-reference to other documentation content
docs/auditor/10.9/admin/monitoringplans/create.md:47 — Dale: wordiness	very long table cell with several concatenated option descriptions; a concise rewrite would require restructuring the cell and risks dropping technical detail

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

[github-actions]

Code Review

Scope: correctness only (bugs, config/routing, scripts, workflows). Content and style are handled by the doc-review workflow.

No blocking issues. This PR touches only docs/auditor/10.9/** — no changes to products.js, docusaurus.config.js, sidebars, scripts, or workflows.

Verified

• Routing is preserved. admin/settings/notifications.md moved to admin/settings/notifications/notifications.md. Because the file name matches its parent folder, Docusaurus treats it as the category index and gives it the folder slug, so the published URL stays https://docs.netwrix.com/docs/auditor/10_9/admin/settings/notifications. The repo encodes this same rule in scripts/generate-audit-list.mjs:283. No redirect needed.
• No broken links. Every reference to the old path was updated (settings/overview.md, monitoringplans/create.md, monitoringplans/activitysummaryemail.md, monitoringplans/azurefiles.md, healthstatus/dashboard/overview.md, healthstatus/summaryemail.md, navigation/recommendations.md). A repo-wide search for the old path in 10.9 returns nothing, and all new .md link targets and in-page anchors (#tenant-environment-options, #restrict-application-access-optional) resolve. Nice catch converting the bare-URL link in azurefiles.md to a .md path so the build actually validates it.
• Sidebar. sidebars/auditor/10.9.js is fully autogenerated, so the new folder needs no sidebar edits. _category_.json position: 50 matches the old page's sidebar_position: 50, so ordering in the Settings section is unchanged.
• MDX safety. Braces in the new PowerShell/Graph placeholders ({APPLICATION_ID_HERE}, {id}) are all inside code fences or inline code, and the <your organization> placeholder is escaped — nothing will be parsed as a JSX expression.

Minor (non-blocking)

1. notifications/_category_.json omits link — every other category in the auditor docs uses overview.md plus an explicit "link": {"type": "doc", "id": "overview"}. This one relies on the implicit category-index convention instead. It works today, but it is load-bearing on the file name: if someone later renames notifications.md to overview.md to match the surrounding convention, without adding a link, the page URL silently becomes .../notifications/overview and the category stops being clickable. Consider adding the explicit link now:

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

2. Old in-page anchors are now dead for external inbound links. The anchors for the former "Enable Notifications via Exchange Online", "Enable Notifications via SMTP", and "Summary Emails and Notifications about Critical Events" sections no longer exist on the notifications page, since those sections became separate pages (the last was also renamed to "Activity and Health Summary Email"). Nothing in the repo links to them, and the page URL itself still resolves, so external deep links land at the top of the page rather than 404ing. Flagging only in case any KB articles or support macros point at those anchors.