docs: improve readability of Policy API guide#3203
Open
marians wants to merge 4 commits into
Open
Conversation
Fix six contraction errors flagged by Vale, split the long multi-clause
sentences in the Motivation section into shorter ones, replace wordy
phrasing ("in order to", "as well as", "allow"), and add a few emphasis
anchors. Lowers the Flesch-Kincaid grade from 13.9 to 13.1 and clears all
Vale errors and sentence-length suggestions, without changing meaning or
dropping detail.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
stone-z
reviewed
Jun 23, 2026
| Among these are a number of capabilities designed for enforcing policies within a cluster. These include built-in types like Network Policies and RBAC, plus external CRDs like Kyverno Cluster Policies or Cilium Network Policies, among others. | ||
|
|
||
| We use and manage tools we believe are the "right tool for the job" and add value for customers. | ||
| We use and manage tools we believe are the **"right tool for the job"** and add value for customers. |
Contributor
There was a problem hiding this comment.
Suggested change
| We use and manage tools we believe are the **"right tool for the job"** and add value for customers. | |
| We use and manage tools we believe are the "right tool for the job" and add value for customers. |
| We expect that Kubernetes and third-party tooling will continue to evolve. We can help our customers move faster if they're not directly tied to tool-specific interfaces that they don't actually want to manage. | ||
|
|
||
| So, we created the Policy API in order to allow Giant Swarm to more seamlessly and transparently move clusters between policy implementations, and to reduce the overall toil of dealing with common security configuration. | ||
| So we created the Policy API for two reasons. The first is to let Giant Swarm move clusters between policy implementations more **seamlessly and transparently**. The second is to reduce the overall toil of dealing with common security configuration. |
Contributor
There was a problem hiding this comment.
Suggested change
| So we created the Policy API for two reasons. The first is to let Giant Swarm move clusters between policy implementations more **seamlessly and transparently**. The second is to reduce the overall toil of dealing with common security configuration. | |
| So we created the Policy API for two reasons. The first is to let Giant Swarm move clusters between policy implementations more seamlessly and transparently. The second is to reduce the overall toil of dealing with common security configuration. |
Co-authored-by: Zach Stone <zach@giantswarm.io>
Co-authored-by: Zach Stone <zach@giantswarm.io>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does / why we need it
Improves the readability of the Policy API guide, #5 on the readability difficulty list (Flesch-Kincaid grade 13.9). This page had genuine prose issues, concentrated in the Motivation section.
Changes:
Vale reports no errors and no sentence-length suggestions. Two heading suggestions remain (
Working with Policy API,PolicyExceptions) — these are intentional, as both are product/type proper nouns that should keep their capitalization. No meaning or detail was changed or removed.Things to check/remember before submitting
last_review_datein the front matter to 2026-06-22.