Add upgrade guide for Access Analyzer install

[darrell-thobe-netwrix]

Summary

• New page: how dspmctl handles upgrades — when the default --target-revision: 1.* wildcard already auto-tracks new releases vs. when you need to pin/roll a specific version
• Steps to set a revision, trigger sync, re-enable auto-sync, and verify the result with argocd app get
• Links the new page from the install section index
• Fixes an unclosed <br> tag in requirements.md (from an earlier vale-autofix commit on dev) that was breaking the MDX build for the whole product

Test plan

• vale clean on changed/new files
• /dale run on changed/new files (two findings fixed: passive voice, undefined CLI acronym)
• DOCS_PRODUCT=accessanalyzer npm run build succeeds

Generated with AI

Co-Authored-By: Claude Code ai@netwrix.com

[github-actions]

Auto-Fix Summary

3 issues fixed, 6 skipped across 3 files

Category	Fixes
Dale: idioms	1
Dale: misplaced-modifiers	1
Dale: passive-voice	1

Skipped (needs manual review)	Reason

| docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md:47 — Dale: passive-voice | 'A child with auto-sync enabled' is a standard absolute construction; every active rewrite is more awkward and risks changing the meaning. |
| docs/accessanalyzer/26.1/install/requirements.md:20 — Dale: idioms | 'at your own risk' is standard technical and legal phrasing rather than a culturally specific idiom; rewriting would weaken the caution. |
| docs/accessanalyzer/26.1/install/requirements.md:33 — Dale: passive-voice | 'a virtual machine provisioned at exactly the stated figure' has no agent stated; an active rewrite would have to assert who provisions the machine, changing the meaning. |
| docs/accessanalyzer/26.1/install/requirements.md:35 — Dale: passive-voice | 'the data that size is designed to hold' — active alternatives ('holds', 'handles') drop the design-intent sense and change the meaning. |
| docs/accessanalyzer/26.1/install/requirements.md:60 — Dale: passive-voice | 'Needed only when a private certificate authority (CA) issued the certificate' is an elliptical table-cell fragment matching the style of the surrounding cells. |
| docs/accessanalyzer/26.1/install/requirements.md:125 — Dale: idioms | 'in place' is common, literal technical phrasing rather than a culturally specific idiom. |

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

[github-actions]

Documentation PR Review

Editorial Review

docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md

• Completeness — Line 13: The section is titled "Check Whether You Need to Act," and the whole page branches on the answer, but it never tells the reader how to check. "Check how you installed the app" leaves them with no way to find out — especially if someone else ran the install. There are two concrete answers available. Suggested fix: add the check as a step, for example: "Look for a target-revision key in /etc/dspm/installer.yaml. The installer writes that key only when a version other than 1.* was pinned (see Installer reference). To confirm what ArgoCD tracks now, run sudo kubectl exec -n argocd -ti deploy/dspmctl -- argocd app get argocd/netwrix and check TARGET REVISION. If it shows 1.*, you don't need any dspmctl steps."

• Clarity — Lines 33 and 39: Step 3 says auto-sync means "later releases in the pinned range deploy without manual steps," but step 1 pinned the exact version 1.1.2, which isn't a range. As written, a reader finishes step 3 believing the next release will arrive on its own, when it won't. Suggested fix: "Turn auto-sync back on so ArgoCD keeps the deployment matching the pinned version and repairs configuration drift on its own. Because 1.1.2 is an exact version, the next release doesn't deploy automatically — run set-revision again when you want to move to it."

• Completeness — Line 22: 1.1.2 reads as a real target rather than a stand-in, and it appears again on lines 25, 64, 74, and 83. A reader copying the commands could pin an unintended version. The page also never says how to find which versions are available. Suggested fix: add a lead-in before step 1 — "Replace 1.1.2 in the commands below with the release you want. Run sudo kubectl exec -n argocd -ti deploy/dspmctl -- argocd app get argocd/netwrix to see the version you're on now." Netwrix style uses angle brackets for placeholders (<version>) if you'd rather not use a sample value at all.

• Structure — Line 4: sidebar_position: 4 is already taken by installer-reference.md. Docusaurus breaks the tie on its own, so the sidebar order of these two pages isn't something the file controls. Suggested fix: set sidebar_position: 5 here, which also puts the upgrade page after the reference page and matches the install → sign-in → reference → upgrade sequence.

• Completeness — Line 19: "the umbrella app" is the first use of the term and carries the whole model of the upgrade — one parent app setting the version for every child. The reader doesn't learn what that means until line 47, after the procedure is over. Suggested fix: define it on first use: "Point the netwrix umbrella app — the parent application that manages one child application per service — at the new version."

• Structure — Line 43: The "Checking the Result" section opens with a bare code block. The reader runs the command before learning what it shows, and it's the first command on the page that isn't dspmctl, right after the intro promised they wouldn't need argocd on the host. Suggested fix: add a lead-in sentence — "dspmctl has no status subcommand, so read the app state through the pod directly:" — then the code block, then the existing explanation.

• Clarity — Line 7: "the install host" appears nowhere else in this section; index.md and requirements.md both say "the server" or "the Linux server." Suggested fix: "You upgrade Access Analyzer with dspmctl on the server where you installed it."

• Clarity — Line 56: "leaves the argocd binary in that pod in a wedged state" — "wedged" is informal and won't be clear to every reader. Same line uses "Ctrl-C," while the docs mostly use "Ctrl+C." Suggested fix: "leaves the argocd binary in that pod unresponsive," and "Ctrl+C."

docs/accessanalyzer/26.1/install/index.md

• Clarity — Line 16: "After you're running" is vague, and the reader isn't the thing that's running. Suggested fix: "Once Access Analyzer is installed and running, see Upgrade to a new version for how new releases roll out and when you need to act."

• Structure — Lines 14–16: Two consecutive one-line paragraphs both opening with "After" now sit between the numbered steps and the "People You Need" heading, and the page's other forward pointer ("Scripting or Troubleshooting an Installation") is at the bottom. Suggested fix: combine them into one paragraph — "After the first sign-in, the Guides show you how to scan your first source. Once Access Analyzer is running, Upgrade to a new version covers how new releases roll out and when you need to act." — or move the upgrade pointer down beside the installer-reference pointer.

docs/accessanalyzer/26.1/install/requirements.md

• No issues found. The <br> to <br/> change is a mechanical MDX fix with no editorial impact.

Summary

10 editorial suggestions across 2 files (1 file clean). 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

2 issues fixed, 5 skipped across 3 files

Category	Fixes
Dale: idioms	1
Dale: xy-slop	1

Skipped (needs manual review)	Reason

| docs/accessanalyzer/26.1/install/requirements.md:35 — Dale: passive-voice | "the data that size is designed to hold" is passive, but the phrasing intentionally mirrors the "Designed for" column in the sizing table on line 26; any active rewrite ("that size handles", "that size targets") shifts a design intent into a capability guarantee, which changes the meaning. |
| docs/accessanalyzer/26.1/install/requirements.md:60 — Dale: passive-voice | "Needed only when a private certificate authority (CA) issued the certificate" is an elliptical passive in a table cell; the terse fragment style matches the surrounding cells, and expanding it to active voice would make the cell inconsistent with the rest of the table. |
| docs/accessanalyzer/26.1/install/requirements.md:20 — Dale: idioms | "at your own risk" is a fixed, literal technical/legal phrase rather than a culturally specific idiom, and it accurately describes accepting a preflight warning. |
| docs/accessanalyzer/26.1/install/index.md:16 — Dale: idioms | "roll out" is standard release-management terminology for this audience, not a figurative expression. |
| docs/accessanalyzer/26.1/install/index.md:6 — Dale: minimizing-difficulty | "answer a few prompts" states the actual scope of the installer's interactive step rather than characterizing the task as easy; no "easily"/"simply" framing is present. |

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