AA 2601: apply prerequisites review feedback (09/03/2026)

[eanandappa99]

Applies the Prereq Updates 09/03/2026 review feedback to docs/accessanalyzer/2601/install/prerequisites.md.

Changes

Feedback	Change
Reword the TLS checklist item	Now reads "TLS certificate option chosen; bring-your-own certificate files prepared"
"REMOVE" the OS-user readability note	Dropped from the <hostname>.key table row
Split the CA trust commands per distro	The block is now RHEL / CentOS / Fedora and Debian / Ubuntu tabs. RHEL writes to /etc/pki/ca-trust/source/anchors/ and runs update-ca-trust; Debian keeps the existing path and update-ca-certificates
Describe the CA trust block	Added a lead-in explaining what the commands do
Describe the openssl block	Added a lead-in covering the SAN, CA-signature, and key-pair checks
Remove the TLS spec pointer	Deleted the "For the full TLS specification..." line
Port to Default Port	Renamed the column in the connector port table
Add a closing reminder	New "Before you start the installer" section at the bottom

Notes for review

• The RHEL command block has been verified and is confirmed correct.
• The feedback marked the .local / .localhost TLD warning as pending validation, so that text is unchanged in this PR.
• The feedback's suggested lead-in text referred to "DSPM". This PR uses "Access Analyzer" instead, to stay consistent with the rest of the page. This change is prose-only: every /etc/dspm/ path, the ca-bundle.crt source file, and the dspm-ca.crt destination filename are unchanged, since those are literal on-disk values.

Scope

This PR covers install/prerequisites.md only. The same content is mirrored in install/quickinstall.md, install/system/network.md, and install/system/certificates.md, which are intentionally left alone here.

Generated with AI

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

[github-actions]

Auto-Fix Summary

4 issues fixed, 5 skipped across 1 files

Category	Fixes
Dale: passive-voice	1
Dale: positional-references	1
Dale: wordiness	2

Skipped (needs manual review)	Reason

| docs/accessanalyzer/2601/install/prerequisites.md:45 — Dale: xy-slop | 'configure static memory allocation (not dynamic/ballooned memory)' is a parenthetical clarification, not the 'x is not y, x is z' construction; rewriting risks losing the technical distinction |
| docs/accessanalyzer/2601/install/prerequisites.md:61 — Dale: xy-slop | 'Use a DNS hostname, not an IP address' states a requirement and its most common misconfiguration; the negation carries necessary technical weight |
| docs/accessanalyzer/2601/install/prerequisites.md:61 — Dale: undefined-acronyms | TLD is a well-known internet/IT term for the sysadmin audience, comparable to the DNS/IP exclusions in the rule |
| docs/accessanalyzer/2601/install/prerequisites.md:152 — Dale: undefined-acronyms | 'base DN' is standard LDAP/Active Directory terminology for this audience, comparable to the LDAP/OU/ACL exclusions in the rule |
| docs/accessanalyzer/2601/install/prerequisites.md:16 — Dale: passive-voice | Checklist items are intentional sentence fragments; past participles here are adjectival, not passive clauses |

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

[github-actions]

Documentation PR Review

Editorial Review

docs/accessanalyzer/2601/install/prerequisites.md

• Clarity — Line 20: "bring-your-own certificate files prepared" introduces a term ("bring-your-own") that appears nowhere else on the page. The TLS certificates section (line 66) presents a single path — "You must prepare the following three files" — with no alternative option described, so "TLS certificate option chosen" leaves the reader looking for a choice the page never explains. Suggested fix: "TLS certificate files prepared in /etc/dspm/ (<hostname>.crt, <hostname>.key, and ca-bundle.crt if an internal CA signed the certificate)"
• Completeness — Line 75: the <hostname>.key row dropped the reason the key permissions matter ("The OS user running the installer must be able to read it — not just root"), and the new paragraph at line 80 describes what the commands do without restating why. A reader who already has a root-only key won't know the chown/chmod step is what makes the installer able to read it. Suggested fix: add the rationale to line 80 — "These commands give the account running the installer read access to the private key, which root-only permissions would block."
• Clarity — Line 80: "Skip the two CA commands for a publicly trusted certificate" makes the reader work out which two of the four commands are the CA commands, and the answer differs per tab. Suggested fix: "Skip the last two commands (cp and the update-ca-* command) for a publicly trusted certificate."
• Completeness — Line 109: the new sentence says the commands confirm "that your CA bundle signed it", but the table at line 76 states ca-bundle.crt is required only when an internal or private CA signs the certificate. A reader with a publicly trusted certificate has no bundle and will hit an error on the second command. Suggested fix: "These commands confirm the certificate covers the right hostname and IP address and that it matches the correct private key. Run the openssl verify command only if an internal or private CA signed the certificate."
• Structure — Lines 229–231: the new "Before installation" section sits at the end of the page and restates what the intro (line 12) and the Checklist (line 14) already establish, so its heading duplicates the purpose of the page itself. The one new fact — that the installer runs preflight checks and stops if they fail — is the part worth keeping, and it's most useful next to the checklist a reader is actually working through. Suggested fix: remove the section and add the new fact under the Checklist heading — "The installer runs preflight checks and stops if they fail, so confirm every item before you start."

Summary

5 editorial suggestions across 1 file. 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

0 issues fixed, 7 skipped across 1 files

Skipped (needs manual review)	Reason

| docs/accessanalyzer/2601/install/prerequisites.md:18 — Dale: passive-voice | Checklist items are past-participle noun fragments ('access confirmed', 'option chosen', 'files prepared', 'address decided'), which is the established convention for a checkbox list. Converting them to active imperatives would change the list's style and intent, not just the grammar. |
| docs/accessanalyzer/2601/install/prerequisites.md:37 — Dale: xy-slop | 'scales with the number of objects rather than the size of on-disk data' is a positive-then-contrast construction carrying real technical information, not the negative-positive 'x is not y, x is z' pattern the rule targets. |
| docs/accessanalyzer/2601/install/prerequisites.md:61 — Dale: xy-slop | 'Use a DNS hostname, not an IP address' is a direct imperative with a necessary corrective contrast in a warning admonition; removing the contrast would drop the specific mistake the warning exists to prevent. |
| docs/accessanalyzer/2601/install/prerequisites.md:61 — Dale: wordiness | 'both break in-cluster DNS resolution and silently break sign-in flows' repeats the verb, but the two failures are distinct (one visible, one silent). Collapsing them risks implying a single failure mode. |
| docs/accessanalyzer/2601/install/prerequisites.md:131 — Dale: misplaced-modifiers | 'Access Analyzer runs without an identity provider, using the local first admin account' — the participle's implied subject matches the sentence subject, so this is not a true dangling modifier. |
| docs/accessanalyzer/2601/install/prerequisites.md:152 — Dale: undefined-acronyms | 'DN' (distinguished name) is standard LDAP/directory terminology for the sysadmin audience, in the same class as the LDAP/OU/ACL exclusions the rule lists. |
| docs/accessanalyzer/2601/install/prerequisites.md:213 — Dale: undefined-acronyms | 'OCI' appears in a reference table cell rather than body prose; the rule scopes define-on-first-use to body prose. |

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