Add installer log guidance — PingCastle Enterprise 4.0

[JoeDibley]

Summary

• Add "Collecting Installer Logs" subsection to enterprisetroubleshooting.md (4.0) covering the /l*v verbose installer log flag
• Add :::note deep links to the new section in both install tabs (Production and Test/POC) in enterpriseinstall.md (4.0)
• Document a known upgrade issue in enterpriseupgrade.md (4.0): the installer sometimes fails to detect the existing installation directory during an in-place upgrade, with the INSTALLFOLDER command-line workaround

Scope: 4.0 only — 3.5 has no troubleshooting page to link to.

Test plan

• Anchor link validated by pre-commit hook
• Dale lint pass on new content — no violations
• Confirm note renders correctly in both tabs and deep link scrolls to section (DOCS_PRODUCT=pingcastle npm run start)

🤖 Generated with Claude Code

[github-actions]

Documentation PR Review

Editorial Review

docs/pingcastle/4.0/enterpriseinstall.md

• Structure — Lines 38 and 133: the cross-reference /docs/pingcastle/4.0/enterprisetroubleshooting#collecting-installer-logs is very likely a broken link that will fail the build. Docusaurus converts version dots to underscores in routes (4.0 → /docs/pingcastle/4_0/), and this link has no .md extension, so it isn't resolved as a file reference. Every other extensionless absolute link in this repo uses the underscore form (/docs/auditor/10_8/...), and every other cross-reference in this file uses a relative link (enterpriserequirements.md, enterpriseauthsetup.md#authentication). Suggested fix: See [Collecting Installer Logs](enterprisetroubleshooting.md#collecting-installer-logs) in the Troubleshooting guide.
• Structure — Lines 37–39 and 132–134: the troubleshooting pointer opens Step 2, before the reader has run the installer or hit a problem. A reader working the procedure top-to-bottom meets a recovery instruction before the task it recovers from. Suggested fix: move the note to the end of Step 2 — after item 10 in the production tab (line 88) and after item 8 in the test/POC tab (line 148) — where a reader who just had the install fail will look.
• Clarity — Lines 38 and 133: "Having trouble installing?" is a rhetorical question addressed to the reader; Netwrix tone is neutral and declarative, and the phrasing doesn't tell the reader what the linked section gives them. Suggested fix: "If the installer fails or exits unexpectedly, see Collecting Installer Logs to generate a verbose log for diagnosis or a support case."

docs/pingcastle/4.0/enterprisetroubleshooting.md

• Clarity — Line 64: the command names the installer pingcastle-enterprise-installer.exe, but every other reference across the 4.0 docs calls it PingCastleEnterpriseInstaller.exe (8 occurrences in enterpriseinstall.md, 3 in enterpriseupgrade.md). A reader who copies this command won't find a file by that name. docs/pingcastle/CLAUDE.md also requires exact, consistent product and component names. Suggested fix: PingCastleEnterpriseInstaller.exe /l*v C:\<log-file-path>\install.log
• Clarity — Line 64: C:\path\to\install.log uses bracket-free prose as a placeholder. Netwrix standards require angle brackets for placeholders. Suggested fix: C:\<log-file-path>\install.log, with a following sentence: "Replace <log-file-path> with a directory that already exists — the installer doesn't create it."
• Completeness — Line 61: /l*v is introduced without explanation. The audience includes administrators new to this product, and the flag is not self-describing. Suggested fix: "Run the installer with the /l*v flag, which writes a verbose log, and a path for the log file:"
• Completeness — Lines 59–67: the section doesn't say that generating the log means re-running the installer to reproduce the failure, which is the first question a reader has after a failed install. Suggested fix: add after line 59 — "The installer writes this log as it runs, so you need to run it again with logging enabled to capture the failure."
• Structure — Line 57: the section sits between "Editing the appsettings.Production.json File" and "Common Errors and Solutions", separating it from the file's other log-collection content. "Viewing Application Logs and Errors" and its "Log Files" subsection (lines 8–30) already cover where logs live and how to download them. Suggested fix: move "Collecting Installer Logs" to directly follow "Log Files" (after line 30) so a reader looking for "how do I get logs" finds all three sources in one place.

docs/pingcastle/4.0/enterpriseupgrade.md

• Clarity — Line 33: the workaround command names the installer pingcastle-enterprise-installer.exe, contradicting PingCastleEnterpriseInstaller.exe in the paragraph directly above it (line 27) and in steps 1 and 2 of the procedure below (lines 41–42). The same inconsistency appears in enterprisetroubleshooting.md. Suggested fix: PingCastleEnterpriseInstaller.exe INSTALLFOLDER="D:\PingCastleEnterprise" /l*v upgrade.log
• Completeness — Lines 30–36: the warning tells the reader what to do if the installer fails to detect the installation directory, but not how to recognize that it happened. Without a symptom, a reader can't tell whether the workaround applies to them, and may only discover the problem after the upgrade finishes. Suggested fix: add the observable sign after the first sentence — for example, "When this happens, the installer proposes the default path C:\Program Files\Netwrix\PingCastleEnterprise instead of your existing directory, and installs alongside your 3.5.1 instance rather than upgrading it." Confirm the actual symptom with engineering before publishing.
• Completeness — Line 33: /l*v upgrade.log appears in the command with no explanation of what it does or where upgrade.log is written. Because the path is relative, the log lands in the installer's working directory, which the reader has no way to infer. This is also the exact topic of the new section added to the troubleshooting guide in this PR, so a cross-reference closes the loop. Suggested fix: after line 36, add "The /l*v flag writes a verbose log to upgrade.log in the directory you run the installer from. See Collecting Installer Logs for details."
• Clarity — Line 30: "In this release" is a vague temporal reference of the same kind as "currently" and "as of this writing", which Netwrix standards prohibit. It also reads ambiguously in a document that discusses two versions. Suggested fix: "In PingCastle Enterprise 4.0, the installer sometimes fails to detect the existing installation directory during an upgrade."
• Completeness — Line 33: INSTALLFOLDER="D:\PingCastleEnterprise\" ends with a backslash immediately before the closing quote. On the Windows command line, that backslash can escape the quote and cause the argument to be parsed incorrectly. Suggested fix: drop the trailing backslash — INSTALLFOLDER="D:\PingCastleEnterprise" — and update line 36 to match. Verify the correct form with engineering, since this is the one command a reader runs when the upgrade has already failed.

Summary

12 editorial suggestions across 3 files. The highest-priority items are the likely broken cross-reference in enterpriseinstall.md (lines 38 and 133), which can fail the build, and the installer filename inconsistency in enterprisetroubleshooting.md (line 64) and enterpriseupgrade.md (line 33). 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

7 issues fixed, 6 skipped across 3 files

Category	Fixes
Dale: misplaced-modifiers	2
Dale: passive-voice	2
Dale: wordiness	3

Skipped (needs manual review)	Reason
docs/pingcastle/4.0/enterprisetroubleshooting.md:189 — Netwrix.OxfordComma	False positive. The sentence 'If Entra ID scanning isn't available, Enterprise and CloudAPI aren't integrated correctly.' is not a series of three or more items — it is a subordinate clause followed by a main clause with a compound subject ('Enterprise and CloudAPI'). The rule regex '\w+,\s+\w+\s+and\b' matches the clause boundary comma. Adding an Oxford comma would be grammatically incorrect, and rewording solely to evade the regex would change the author's phrasing without improving clarity.
docs/pingcastle/4.0/enterprisetroubleshooting.md:99 — Dale: positional-references	"The last error relates to the missing update KB2533623" points at the preceding screenshot; no anchor or caption exists to reference instead, and naming a specific error could misidentify which image is meant
docs/pingcastle/4.0/enterprisetroubleshooting.md:155 — Dale: passive-voice	"TCP/IP connectivity enabled on SQL Server" and "Firewall configured to allow remote connections" are requirement fragments describing required states, not passive clauses; rewriting them would change the list's established form
docs/pingcastle/4.0/enterprisetroubleshooting.md:158 — Dale: xy-slop	"The application pool identity needs these permissions, not your user account" is positive-then-negative contrast that carries the actual warning; the rule targets the "x is not y, x is z" order
docs/pingcastle/4.0/enterpriseupgrade.md:27 — Dale: idioms	"run the new installer on top of your existing 3.5.1 installation" is established technical phrasing for in-place upgrades; literal alternatives read less clearly
docs/pingcastle/4.0/enterpriseinstall.md:41 — Dale: idioms	"The installer wizard walks you through..." is standard, widely understood documentation phrasing rather than a culturally specific expression

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