Skip to content

Edits the by Tech Writer Agent following the F5 Technical Writing Sty… - #2204

Merged
travisamartin merged 1 commit into
nic/plm-install-upgradefrom
nic/plm-install-upgrade-edits
Aug 13, 2026
Merged

Edits the by Tech Writer Agent following the F5 Technical Writing Sty…#2204
travisamartin merged 1 commit into
nic/plm-install-upgradefrom
nic/plm-install-upgrade-edits

Conversation

@travisamartin

Copy link
Copy Markdown
Contributor

PR description draft

Style edits: plm-installation.md and plm-upgrade.md

This PR applies style edits to both PLM docs to align them with the F5 Technical Writing Style Guide. No technical content was changed.

Product naming (f5-product-names)

Replaced all uses of the NIC abbreviation in body prose with the full product name NGINX Ingress Controller. Abbreviating NGINX product names isn't permitted. Shell commands, variable names (NIC_NAMESPACE, NIC_RELEASE, NIC_POD), and Helm release names (nic) were left unchanged because they are literal command syntax.

Second person and active voice (second-person, active-voice)

  • "This guide installs / upgrades" → "Use this guide to install / upgrade" — the guide doesn't act; the reader does.
  • "The k8s.nginx.org/v1 Policy manifest…does not need to be rewritten" → "You don't need to rewrite…"
  • "When namespace is omitted, NGINX Ingress Controller defaults…" → "When you omit the namespace…"

Contractions and tense (contractions, tense)

  • "does not" / "has not" / "is not" / "cannot" → "doesn't" / "hasn't" / "isn't" / "can't" throughout.
  • "you will have" → "you'll have".

Word list (word-list)

  • "substitute" → "replace"
  • "PLM storage enabled" → "PLM storage turned on" (enable-disable)

Ambiguous pronouns (pronouns)

  • "It deliberately excludes the App Protect CRDs" → "The bundle deliberately excludes…"
  • "Both mechanisms operate independently" → "The two mechanisms operate independently"
  • "It does this by adding the finalizer" added to resolve "PLM adopts every resource" → ambiguous follow-on sentence

Conditional sentences — condition first (conditional-sentences)

  • "You'll pass all four values…when you run helm upgrade" → "When you run helm upgrade, pass all four values…"
  • "Before you turn on PLM storage, migrate every such Ingress" — preceding sentence restructured so the condition leads.
  • Troubleshooting bullets restructured so the condition or trigger appears before the action.

Semicolons (semicolons)

  • `--reuse-values` preserves…; the `--set` flags overlay PLM storage on top split into two sentences.
  • Credentials Secret list item split from semicolon join into two sentences.

Paragraph structure and instruction order (paragraph-structure, step-formatting)

  • In plm-installation.md, the install section was restructured: "install with --skip-crds. Apply…first" was contradictory. Rewritten as: "you must apply the controller's own CRDs before running helm install", with the kubectl apply command following naturally.
  • Extra blank line before a shell block removed.
  • "Send a normal request to confirm the application responds." (period) → colon, so the shell block reads as the step continuation.

Headings (headings, step-numbers-in-headings)

  • ## Section 1: Attach to a VirtualServer## Attach to a VirtualServer
  • ## Section 2: Attach to an Ingress## Attach to an Ingress
  • ## Create the NIC Policy## Create the Policy
  • ### 1. Upgrade NIC to enable PLM### 1. Upgrade NGINX Ingress Controller with PLM storage (both sections)

The "Section N:" prefix and numbered subheadings act as step numbers in headings, which isn't permitted. The cross-reference prose was updated to use a short bulleted list of links to the renamed headings.

Line wrapping

Removed all manual mid-sentence line breaks in prose. Text now wraps at the editor margin instead of at an arbitrary column, making diffs easier to read.‌​​​‍‌​‌⁣​‍‍​⁣⁣‌‌​‍​‌‌‍‍‍‌‍‌​⁣‍⁣‌​‌‍‌‌⁣‌‍​⁣‌‌⁣⁣⁣⁣⁣⁣‍⁣‌‌​‍⁠

@travisamartin
travisamartin requested a review from a team as a code owner August 12, 2026 20:01
@github-actions github-actions Bot added documentation Improvements or additions to documentation product/nic Issues related to NGINX Ingress Controller labels Aug 12, 2026
This tutorial uses the following example values. If you use different values,
substitute them consistently throughout.
- `kubectl` access to a Kubernetes cluster.
- Helm installed.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to specify the Helm version?

@travisamartin
travisamartin force-pushed the nic/plm-install-upgrade-edits branch from c753217 to cebfe4d Compare August 12, 2026 20:29
@travisamartin
travisamartin merged commit 570eb71 into nic/plm-install-upgrade Aug 13, 2026
5 of 6 checks passed
@travisamartin
travisamartin deleted the nic/plm-install-upgrade-edits branch August 13, 2026 13:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation product/nic Issues related to NGINX Ingress Controller

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants