Add Gruntwork Way! #2852
Add Gruntwork Way! #2852
Conversation
Take the contents of https://github.com/gruntwork-io/way and add it to the main docs site.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughThe PR introduces comprehensive documentation for The Gruntwork Way developer platform framework, organized into Introduction, Principles, Platform Components, Resources, and Why sections. Configuration updates integrate this documentation into the site structure, and tooling changes include spell-checking refactoring and a husky dependency addition. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
This PR is being reviewed by Cursor Bugbot
Details
Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.
To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
🧹 Nitpick comments (38)
docs/2.0/way/principles/technical-foundations/_category_.json (1)
1-5: Minor formatting: Remove trailing whitespace.Line 3 has a trailing space after the position value. While this doesn't affect JSON parsing, it's worth cleaning up for consistency with other category descriptor files.
{ "label": "Technical Foundations", - "position": 4 + "position": 4 }docs/2.0/way/solution/interfaces/overview.md (1)
1-26: Consider varying sentence structure for better readability.The documentation effectively covers all four interface types, but each section follows an identical pattern starting with "The [X] works well when developers want to..." Varying this phrasing would add better flow and readability while maintaining the same informative content.
For example, you might alternate between:
- "Use the Web UI when..."
- "The CLI works well for..."
- "The API enables..."
- "With AI/MCP, developers can..."
This is a stylistic improvement rather than a correctness issue, but it would enhance the reading experience.
docs/2.0/way/solution/overview.md (1)
26-26: Add newline at end of file.Markdown files should end with a newline character as per standard convention.
docs/2.0/way/resources/glossary.md (1)
41-41: Add newline at end of file.Markdown files should end with a newline character as per standard convention.
docs/2.0/way/principles/technical-foundations/build-platform-components.md (1)
15-15: Add newline at end of file.Markdown files should end with a newline character as per standard convention.
docs/2.0/way/principles/technical-foundations/define-all-live-infrastructure-as-pattern-instances.md (1)
26-26: Add newline at end of file.Markdown files should end with a newline character as per standard convention.
docs/2.0/way/principles/technical-foundations/represent-all-patterns-as-code.md (1)
54-54: Add newline at end of file.Markdown files should end with a newline character as per standard convention.
docs/2.0/way/principles/technical-foundations/embrace-immutable-infrastructure.md (1)
19-19: Add newline at end of file.Markdown files should end with a newline character as per standard convention.
docs/2.0/way/intro/share-your-feedback.md (1)
6-9: Minor polish opportunities for this feedback page.A few small refinements would improve readability:
- Wrap the bare URL (line 9) in markdown link syntax so it renders as a clickable link:
[GitHub](https://github.com/gruntwork-io/way)- Reduce repeated phrasing (line 8): The "maybe...or maybe" construction could be tightened for better flow, e.g., "But if your experience differs or we got something wrong, let us know!"
docs/2.0/way/intro/welcome.md (2)
1-4: Add document ID to front-matter.Per documentation best practices in this repository, add
id: welcometo the front-matter to explicitly set the document identifier, matching the filename. This ensures consistency with other documentation pages.--- title: Welcome! sidebar_position: 1 +id: welcome ---Based on learnings from earlier PRs in this repository.
39-39: Use hyphenated compound modifier.Line 39: "open source DevOps" should be "open-source DevOps" when used as a compound modifier before "tooling."
-* **Makers** - We've created leading open source DevOps tooling like [OpenTofu](https://opentofu.org/) (co-founder), [Terragrunt](https://terragrunt.gruntwork.io/), [Terratest](https://terratest.gruntwork.io/), [Runbooks](https://runbooks.gruntwork.io), [Boilerplate](https://github.com/gruntwork-io/boilerplate), and [Cloud Nuke](https://github.com/gruntwork-io/cloud-nuke). +* **Makers** - We've created leading open-source DevOps tooling like [OpenTofu](https://opentofu.org/) (co-founder), [Terragrunt](https://terragrunt.gruntwork.io/), [Terratest](https://terratest.gruntwork.io/), [Runbooks](https://runbooks.gruntwork.io), [Boilerplate](https://github.com/gruntwork-io/boilerplate), and [Cloud Nuke](https://github.com/gruntwork-io/cloud-nuke).docs/2.0/way/solution/patterns/types.md (2)
1-4: Add document ID to front-matter.For consistency with documentation best practices in this repo, add
id: typesto the front-matter.--- sidebar_position: 2 title: Types +id: types ---
58-73: Vary sentence structure in the Runbooks and Other sections.Lines 60–62 have three sentences that begin with "Runbooks," which reads a bit monotonously. Consider rephrasing one or two for variety:
Example refinement:
-Runbooks are step-by-step (and sometimes interactive) operational procedures for infrastructure tasks such as incident response, guided code generation, troubleshooting, and recovery. - -Runbooks can be especially well-suited to generating code based on [templates](#templates). +Runbooks are step-by-step (and sometimes interactive) operational procedures for infrastructure tasks such as incident response, guided code generation, troubleshooting, and recovery. + +They're especially well-suited to generating code based on [templates](#templates).This is a minor stylistic improvement; the current version is perfectly readable.
docs/2.0/way/solution/platform/maintain/iac-updater.md (2)
1-4: Add document ID to front-matter.For consistency with documentation best practices, add
id: iac-updaterto the front-matter.--- sidebar_position: 2 title: IaC Updater +id: iac-updater ---
6-8: Convert emphasis to proper markdown heading.Line 8 uses bold (
**...**) to format what is semantically a heading. Use a proper heading syntax instead (e.g.,## Update out-of-date IaC or tooling versionsor### Update out-of-date IaC or tooling versions).# IaC Updater -**Update out-of-date IaC or tooling versions** +## Update out-of-date IaC or tooling versions The IaC updater identifies infrastructure using outdated patterns or tool versions and helps you modernize it. This prevents technical debt from accumulating as your patterns and tools evolve.This aligns with markdown best practices and improves document structure for readers using heading-based navigation.
docs/2.0/way/intro/who-this-is-for.md (1)
20-22: Tighten redundant phrasing: "component parts" → "components" or "parts".Lines 20 and 22 both use "component parts," which is unnecessarily wordy. Try simplifying to either "components" or "parts" for clarity.
-Your collective maturity level for the "developer platform" is really just the collection of maturity levels for its component parts. +Your collective maturity level for the "developer platform" is really just the collection of maturity levels for its components. -In general, the component parts track these maturity levels: +In general, the components track these maturity levels:docs/2.0/way/solution/patterns/infrastructure-modules/categories.md (1)
10-10: Simplify redundant "subject matter expertise topics" phrasing.The phrase "subject matter expertise topics (SME topics)" uses "subject" unnecessarily since SME already stands for "subject matter expertise." Streamline to either "expertise topics" or just "SME topics."
-Based on years of experience, we've identified the following **categories** of infrastructure modules. Each category has one or more **subject matter expertise topics (SME topics)**. Each SME topic has one or more infrastructure modules. +Based on years of experience, we've identified the following **categories** of infrastructure modules. Each category has one or more **SME topics**. Each SME topic has one or more infrastructure modules.docs/2.0/way/why/overview.md (2)
10-31: Adjust heading levels for proper document structure.The document jumps from h1 (
#) to h3 (###) for the three fundamental concerns, skipping h2. This can impact accessibility and document outline generation. Consider using h2 (##) for these subsections instead.Apply this diff to fix the heading levels:
-### 1. Velocity +## 1. Velocity **Velocity is how quickly you ship changes to production.** Software teams add value by shipping new features that drive business impact. This applies to both: - **Applications** - Launching new customer-facing or internal features - **Infrastructure** - Launching or updating infrastructure to support applications -### 2. Governance +## 2. Governance **Governance is how you protect your business and customers.** Every time you ship a change, you need to answer critical questions like: - **Is it cost-effective?** Can we afford to run this? - **Is it compliant?** Does it satisfy our legal obligations? - **Is it secure?** Will it protect our customers' data? - **Is it reliable?** Will this work as expected? -### 3. Maintainability +## 3. Maintainability
26-29: Optional: Consider minor style refinements.A few optional style improvements to consider:
- Lines 26-29: The repeated "Is it..." structure creates good parallel rhythm, though you could vary it if preferred
- Line 40: "many different ways" could be simplified to "many ways"
- Line 52: "moment in time" could be shortened to "moment" or "time"
These are minor readability suggestions and completely optional.
Also applies to: 40-40, 52-52
docs/2.0/way/why/governance.mdx (1)
11-11: Optional: Minor style refinements.A few optional style improvements flagged by static analysis:
- Line 11: "hard to do" could use a synonym like "difficult"
- Line 17: "Cost effectiveness" could be hyphenated as "Cost-effectiveness"
- Line 80: "very large surface area" could be simplified to "large surface area"
These are purely stylistic and optional.
Also applies to: 17-17, 80-80
docs/2.0/way/principles/developer-experience/enable-developer-self-service.md (1)
18-18: Optional: Style suggestion.If you'd like, "hard to get right" could be replaced with "difficult to implement" or "challenging to achieve" for variety, though the current phrasing is perfectly clear.
docs/2.0/way/principles/core-philosophy/your-developer-platform-is-a-product.md (1)
14-15: Optional: Style variation.Static analysis flagged the repeated "Products" sentence beginnings and "need to" phrases. However, the parallel structure here is actually effective for creating rhythm and emphasis. If you prefer variation, you could rephrase, but the current structure works well pedagogically.
Also applies to: 17-17
docs/2.0/way/solution/platform/maintain/drift-detector.md (1)
8-8: Replace bold emphasis with a proper heading level.Line 8 uses bold formatting (
**...**) when it should use a markdown heading to maintain consistent hierarchy. This also resolves the MD036 linter warning.Apply this diff:
-**Detect drift between code and cloud** +## Detect drift between code and clouddocs/2.0/way/solution/platform/deploy/pipelines.md (1)
8-8: Replace bold emphasis with a proper heading level.Like the other component pages, this uses bold formatting when a proper heading would be more semantically correct and resolve the MD036 linter warning.
Apply this diff:
-**How you deploy infrastructure changes** +## How you deploy infrastructure changesdocs/2.0/way/solution/patterns/where-to-store-them.md (1)
13-13: Tighten the phrasing to improve clarity.The phrase "with respect to" is wordier than necessary. Consider a shorter alternative like "for" or "regarding" to make the sentence more direct.
Apply this diff:
-- **Software artifact repository.** Tools like [Artifactory](https://jfrog.com/artifactory/) or [Sonatype Nexus Repository](https://www.sonatype.com/products/sonatype-nexus-repository) can _store_ all the different pattern types, but they often have limited _functionality_ with respect to these infrastructure-as-code pattern types. +- **Software artifact repository.** Tools like [Artifactory](https://jfrog.com/artifactory/) or [Sonatype Nexus Repository](https://www.sonatype.com/products/sonatype-nexus-repository) can _store_ all the different pattern types, but they often have limited _functionality_ for these infrastructure-as-code pattern types.docs/2.0/way/why/maintainability.md (2)
21-21: Simplify "a variety of forms" for directness.Minor wordiness: "a variety of forms" can be shortened. Consider "takes on several forms" or just "includes".
Apply this diff:
-In the infrastructure world, debt takes on a variety of forms: +In the infrastructure world, debt takes several forms:
26-26: Tighten "many different ways" for clarity.Minor wording improvement: "many different ways" is slightly redundant. Consider "various ways" or "different ways".
Apply this diff:
-- **Non-standardization** - Your organization solves the same problem in many different ways +- **Non-standardization** - Your organization solves the same problem in various waysdocs/2.0/way/solution/platform/operate/unit-browser.md (1)
8-8: Replace bold emphasis with a proper heading level.Consistent with other component pages, this should use a proper heading instead of bold formatting to resolve the MD036 linter warning and maintain structural consistency.
Apply this diff:
-**How to browse what infrastructure is deployed** +## How to browse what infrastructure is deployeddocs/2.0/way/principles/failure-modes.md (1)
63-63: Hyphenate "open-source" when used as a compound adjective.When "open source" modifies a noun, it should be hyphenated per standard grammar conventions.
Apply this diff:
-First, as platform engineers, look for pre-built, battle-tested patterns wherever possible. These could be open source modules, or commercial module catalogs like the [Gruntwork AWS IaC Library](https://docs.gruntwork.io/2.0/docs/library/concepts/overview). +First, as platform engineers, look for pre-built, battle-tested patterns wherever possible. These could be open-source modules, or commercial module catalogs like the [Gruntwork AWS IaC Library](https://docs.gruntwork.io/2.0/docs/library/concepts/overview).docs/2.0/way/why/velocity.md (1)
82-88: Resolve the TODO before launch.Line 86 contains an unresolved TODO comment about updating a URL. Please add the relevant link or remove the comment if the reference is no longer needed.
docs/2.0/way/solution/patterns/infrastructure-modules/authoring.md (1)
31-33: Use hyphens for compound adjectives."Open source" should be hyphenated as "open-source" when modifying a noun (open-source infrastructure modules). This appears in multiple locations throughout this file.
Apply these diffs to fix hyphenation:
- 1. **Build in-house** - You build the infrastructure module yourself from scratch. This gives you full control, but also the highest maintenance burden. (high control, low convenience) - 2. **Use open source infrastructure modules** - You find community-authored infrastructure modules... + 1. **Build in-house** - You build the infrastructure module yourself from scratch. This gives you full control, but also the highest maintenance burden. (high control, low convenience) + 2. **Use open-source infrastructure modules** - You find community-authored infrastructure modules...Also fix lines 40 and 112:
- For example, you use an open source AWS Lambda module, but write your own Acme AWS Lambda module that uses the open source AWS Lambda module. + For example, you use an open-source AWS Lambda module, but write your own Acme AWS Lambda module that uses the open-source AWS Lambda module.- In our experience, the better option is to deal with empty versions and fewer git repos. Better yet, you can write tooling to automate nearly all aspects of empty versions (like your [IaC updater](/2.0/way/solution/platform/maintain/iac-updater)). There's also tooling available to manage many git repos at once (like our open source tool, [git-xargs](https://github.com/gruntwork-io/git-xargs)), but using these can be cumbersome. + In our experience, the better option is to deal with empty versions and fewer git repos. Better yet, you can write tooling to automate nearly all aspects of empty versions (like your [IaC updater](/2.0/way/solution/platform/maintain/iac-updater)). There's also tooling available to manage many git repos at once (like our open-source tool, [git-xargs](https://github.com/gruntwork-io/git-xargs)), but using these can be cumbersome.docs/2.0/way/solution/patterns/overview.md (1)
27-41: Consider tightening language for clarity and conciseness.The static analysis suggestions here are valid improvements (though not blockers):
- Line 27: Replace "subject matter expertise" with just "subject expertise" or "expertise"
- Line 27: Change "all of the following" to "all the following"
- Line 39: Replace "as you can see in the list above" with something more direct
- Line 41: Replace "We talk about patterns" with "Patterns are..."
docs/2.0/way/solution/patterns/good-patterns.md (1)
157-162: Use hyphen for "peer-reviewed".Line 159 should use a hyphen for the compound adjective: "It was written by a Gruntwork subject matter expert, and peer-reviewed by other Gruntwork subject matter experts..."
- It was written by a Gruntwork subject matter expert, and peer reviewed by other Gruntwork subject matter experts, so it is **vetted.** + It was written by a Gruntwork subject matter expert, and peer-reviewed by other Gruntwork subject matter experts, so it is **vetted.**docs/2.0/way/principles/developer-experience/pre-built-patterns-are-your-leverage.md (1)
20-23: Use hyphen for "in-house".Line 22 should use a hyphen: "Patterns can be authored in-house, or 'vendored' from open-source or commercial pattern libraries..."
Note: While you're there, "open source" should also be hyphenated to "open-source" as a compound adjective.
- Patterns can be authored inhouse, or "vendored" from open source or commercial pattern libraries (like [Gruntwork IaC Library](https://docs.gruntwork.io/2.0/docs/library/concepts/overview)). + Patterns can be authored in-house, or "vendored" from open-source or commercial pattern libraries (like [Gruntwork IaC Library](https://docs.gruntwork.io/2.0/docs/library/concepts/overview)).docs/2.0/way/solution/platform/deploy/catalog.md (2)
6-9: Use a heading instead of emphasis for the tagline.Line 8 should be formatted as a markdown heading (###) rather than bold emphasis to maintain proper document structure.
- # Catalog - - **Where you store your organization's patterns** + # Catalog + + ### Where you store your organization's patternsAlternatively, if this is intentional styling, you can suppress the MD036 linting rule for this line.
56-59: Use hyphen for "open-source" compound adjective.Line 58 should use a hyphen: "...Terragrunt, we expose a terragrunt catalog command that presents a Terminal UI to select the desired module from a specified set of git repos with an open-source tool."
Actually, on closer inspection, the text reads "In our open source tool, Terragrunt..." which should be "In our open-source tool, Terragrunt..."
- In our open source tool, Terragrunt, we expose a [terragrunt catalog](https://terragrunt.gruntwork.io/docs/features/catalog/) command that presents a Terminal UI to select the desired module from a specified set of git repos. + In our open-source tool, Terragrunt, we expose a [terragrunt catalog](https://terragrunt.gruntwork.io/docs/features/catalog/) command that presents a Terminal UI to select the desired module from a specified set of git repos.docs/2.0/way/solution/platform/deploy/runbooks.md (2)
8-8: Use proper markdown heading instead of emphasis.Line 8 uses bold text to present a descriptor, but it reads more like a section heading. Consider converting this to a proper markdown heading (e.g.,
##) or reorganizing the content structure for consistency with other sections.-**How developers configure an infrastructure module instance** +## How developers configure an infrastructure module instance
150-150: Hyphenate "open-source" and wrap URL in markdown link syntax.Line 150 uses bare "open source" without hyphenation and contains a bare URL reference. Consider using "open-source" as a compound adjective and proper markdown link syntax for consistency.
-Gruntwork maintains an open source tool called [Gruntwork Runbooks](https://runbooks.gruntwork.io/) that is based on all the insights and philosophy that we capture here. Check it out! +Gruntwork maintains an open-source tool called [Gruntwork Runbooks](https://runbooks.gruntwork.io/) that is based on all the insights and philosophy that we capture here. Check it out!
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
yarn.lockis excluded by!**/yarn.lock,!**/*.lock
📒 Files selected for processing (66)
docs/2.0/way/authorship.md(1 hunks)docs/2.0/way/intro/_category_.json(1 hunks)docs/2.0/way/intro/how-to-use-this.md(1 hunks)docs/2.0/way/intro/share-your-feedback.md(1 hunks)docs/2.0/way/intro/welcome.md(1 hunks)docs/2.0/way/intro/who-this-is-for.md(1 hunks)docs/2.0/way/principles/_category_.json(1 hunks)docs/2.0/way/principles/core-philosophy/_category_.json(1 hunks)docs/2.0/way/principles/core-philosophy/the-platform-is-a-balancing-act.md(1 hunks)docs/2.0/way/principles/core-philosophy/your-developer-platform-is-a-product.md(1 hunks)docs/2.0/way/principles/developer-experience/_category_.json(1 hunks)docs/2.0/way/principles/developer-experience/enable-developer-self-service.md(1 hunks)docs/2.0/way/principles/developer-experience/make-good-practices-the-default.md(1 hunks)docs/2.0/way/principles/developer-experience/pre-built-patterns-are-your-leverage.md(1 hunks)docs/2.0/way/principles/developer-experience/shift-left.md(1 hunks)docs/2.0/way/principles/failure-modes.md(1 hunks)docs/2.0/way/principles/governance-maintainability/_category_.json(1 hunks)docs/2.0/way/principles/governance-maintainability/guardrails-over-gates.md(1 hunks)docs/2.0/way/principles/governance-maintainability/offer-golden-paths.md(1 hunks)docs/2.0/way/principles/overview.md(1 hunks)docs/2.0/way/principles/technical-foundations/_category_.json(1 hunks)docs/2.0/way/principles/technical-foundations/build-platform-components.md(1 hunks)docs/2.0/way/principles/technical-foundations/define-all-live-infrastructure-as-pattern-instances.md(1 hunks)docs/2.0/way/principles/technical-foundations/embrace-immutable-infrastructure.md(1 hunks)docs/2.0/way/principles/technical-foundations/represent-all-patterns-as-code.md(1 hunks)docs/2.0/way/principles/technical-foundations/use-gitops.md(1 hunks)docs/2.0/way/resources/_category_.json(1 hunks)docs/2.0/way/resources/glossary.md(1 hunks)docs/2.0/way/resources/sources.md(1 hunks)docs/2.0/way/solution/_category_.json(1 hunks)docs/2.0/way/solution/interfaces/_category_.json(1 hunks)docs/2.0/way/solution/interfaces/overview.md(1 hunks)docs/2.0/way/solution/overview.md(1 hunks)docs/2.0/way/solution/patterns/_category_.json(1 hunks)docs/2.0/way/solution/patterns/good-patterns.md(1 hunks)docs/2.0/way/solution/patterns/infrastructure-modules/_category_.json(1 hunks)docs/2.0/way/solution/patterns/infrastructure-modules/authoring.md(1 hunks)docs/2.0/way/solution/patterns/infrastructure-modules/categories.md(1 hunks)docs/2.0/way/solution/patterns/infrastructure-modules/overview.md(1 hunks)docs/2.0/way/solution/patterns/overview.md(1 hunks)docs/2.0/way/solution/patterns/types.md(1 hunks)docs/2.0/way/solution/patterns/where-to-store-them.md(1 hunks)docs/2.0/way/solution/platform/_category_.json(1 hunks)docs/2.0/way/solution/platform/deploy/_category_.json(1 hunks)docs/2.0/way/solution/platform/deploy/catalog.md(1 hunks)docs/2.0/way/solution/platform/deploy/pipelines.md(1 hunks)docs/2.0/way/solution/platform/deploy/runbooks.md(1 hunks)docs/2.0/way/solution/platform/maintain/_category_.json(1 hunks)docs/2.0/way/solution/platform/maintain/drift-detector.md(1 hunks)docs/2.0/way/solution/platform/maintain/iac-updater.md(1 hunks)docs/2.0/way/solution/platform/maintain/importer.md(1 hunks)docs/2.0/way/solution/platform/maintain/scorecard.md(1 hunks)docs/2.0/way/solution/platform/operate/_category_.json(1 hunks)docs/2.0/way/solution/platform/operate/dashboards.md(1 hunks)docs/2.0/way/solution/platform/operate/registry.md(1 hunks)docs/2.0/way/solution/platform/operate/unit-browser.md(1 hunks)docs/2.0/way/solution/platform/overview.md(1 hunks)docs/2.0/way/why/_category_.json(1 hunks)docs/2.0/way/why/governance.mdx(1 hunks)docs/2.0/way/why/maintainability.md(1 hunks)docs/2.0/way/why/overview.md(1 hunks)docs/2.0/way/why/velocity.md(1 hunks)docusaurus.config.js(1 hunks)sidebars.js(2 hunks)sidebars/way.js(1 hunks)src/css/custom.css(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
docs/**/*.mdx
📄 CodeRabbit inference engine (.cursor/rules/gitlab-background.mdc)
Whenever presenting information that diverges between GitHub and GitLab, use the and components to distinguish the two sets of information UNLESS the distinction is just changing one word. For example, GitHub has pull requests and GitLab has merge requests, so we can just say '... pull/merge requests...' and not need full .
Files:
docs/2.0/way/why/governance.mdx
🧠 Learnings (2)
📚 Learning: 2025-07-23T21:18:42.052Z
Learnt from: CR
Repo: gruntwork-io/docs PR: 0
File: .cursor/rules/tone.mdc:0-0
Timestamp: 2025-07-23T21:18:42.052Z
Learning: Avoid buzzwords and clichés in documentation; simplify DevOps concepts for clarity.
Applied to files:
docs/2.0/way/principles/developer-experience/shift-left.mddocs/2.0/way/principles/technical-foundations/embrace-immutable-infrastructure.md
📚 Learning: 2025-07-17T18:43:27.029Z
Learnt from: ZachGoldberg
Repo: gruntwork-io/docs PR: 2663
File: docs/2.0/docs/pipelines/architecture/change-types.md:1-6
Timestamp: 2025-07-17T18:43:27.029Z
Learning: In the gruntwork-io/docs repository, document IDs should match the filename (without extension) rather than being namespaced. For example, a file named "change-types.md" should have `id: change-types` in the front matter.
Applied to files:
docs/2.0/way/intro/welcome.md
🪛 LanguageTool
docs/2.0/way/intro/who-this-is-for.md
[style] ~20-~20: This phrase is redundant. Consider writing “components” or “parts”.
Context: ...e collection of maturity levels for its component parts. In general, the component parts track...
(COMPONENT_PART)
[style] ~22-~22: This phrase is redundant. Consider writing “components” or “parts”.
Context: ...r its component parts. In general, the component parts track these maturity levels: - **Ad ho...
(COMPONENT_PART)
docs/2.0/way/solution/interfaces/overview.md
[style] ~16-~16: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...CLI The CLI works well when developers want to interact with your platform directly fr...
(REP_WANT_TO_VB)
docs/2.0/way/principles/governance-maintainability/guardrails-over-gates.md
[uncategorized] ~14-~14: Do not mix variants of the same word (‘judgment’ and ‘judgement’) within a single text.
Context: ...ail, you are reducing that manual human judgment down to a narrowly scoped rule that sys...
(EN_WORD_COHERENCY)
docs/2.0/way/principles/developer-experience/pre-built-patterns-are-your-leverage.md
[grammar] ~22-~22: Use a hyphen to join words.
Context: ...uthored inhouse, or "vendored" from open source or commercial pattern libraries (...
(QB_NEW_EN_HYPHEN)
docs/2.0/way/principles/failure-modes.md
[grammar] ~63-~63: Use a hyphen to join words.
Context: ...s wherever possible. These could be open source modules, or commercial module cat...
(QB_NEW_EN_HYPHEN)
docs/2.0/way/why/overview.md
[style] ~28-~28: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...s it satisfy our legal obligations? - Is it secure? Will it protect our custom...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~29-~29: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ill it protect our customers' data? - Is it reliable? Will this work as expect...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~40-~40: ‘many different ways’ might be wordy. Consider a shorter alternative.
Context: ...organization solves the same problem in many different ways Achieving maintainability is about ide...
(EN_WORDINESS_PREMIUM_MANY_DIFFERENT_WAYS)
[style] ~52-~52: This phrase is redundant. Consider writing “moment” or “time”.
Context: ...inability for your organization at this moment in time, and adjusting that balance as your nee...
(MOMENT_IN_TIME)
docs/2.0/way/solution/patterns/infrastructure-modules/authoring.md
[grammar] ~32-~32: Use a hyphen to join words.
Context: ... control, low convenience) 2. Use open source infrastructure modules - You fi...
(QB_NEW_EN_HYPHEN)
[grammar] ~40-~40: Use a hyphen to join words.
Context: ...per module. For example, you use an open source AWS Lambda module, but write your...
(QB_NEW_EN_HYPHEN)
[grammar] ~40-~40: Use a hyphen to join words.
Context: ...cme AWS Lambda module that uses the open source AWS Lambda module. 3. Fork - ...
(QB_NEW_EN_HYPHEN)
[grammar] ~112-~112: Use a hyphen to join words.
Context: ...ge many git repos at once (like our open source tool, [git-xargs](https://github....
(QB_NEW_EN_HYPHEN)
[style] ~130-~130: Consider removing “of” to be more concise
Context: ...should be scheduled for retirement when ALL of the following are true: - **Better alterna...
(ALL_OF_THE)
[style] ~135-~135: Consider replacing ‘often’ with a more meaningful word.
Context: ... a module if it is simply not used very often. By reducing your surface area, you inc...
(VERY_RB_STYLE)
docs/2.0/way/principles/core-philosophy/your-developer-platform-is-a-product.md
[style] ~14-~14: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...e a compelling case on why to use it. - Products have competitive alternatives, you co...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~14-~14: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...oose to do it themselves (DIY), and you need to highlight the clear advantages over DIY...
(REP_NEED_TO_VB)
[style] ~15-~15: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ear advantages over DIY to end users. - Products need data to tell you about usage and...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~17-~17: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...about what their customer needs. You'll need to do this, too.
(REP_NEED_TO_VB)
docs/2.0/way/solution/patterns/where-to-store-them.md
[style] ~13-~13: ‘with respect to’ might be wordy. Consider a shorter alternative.
Context: ...they often have limited functionality with respect to these infrastructure-as-code pattern ty...
(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
docs/2.0/way/principles/technical-foundations/represent-all-patterns-as-code.md
[style] ~25-~25: To elevate your writing, try using a synonym here.
Context: ...id the original configuration, and it's hard to track or know about any updates to t...
(HARD_TO)
[grammar] ~34-~34: Use a hyphen to join words.
Context: ... be reverted if needed. Code can be peer reviewed, and automated tests can run to...
(QB_NEW_EN_HYPHEN)
[style] ~49-~49: ‘emergency situations’ might be wordy. Consider a shorter alternative.
Context: ... code does take more time. Sometimes in emergency situations, engineers might need to optimize for s...
(EN_WORDINESS_PREMIUM_EMERGENCY_SITUATIONS)
docs/2.0/way/solution/patterns/types.md
[style] ~61-~61: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ration, troubleshooting, and recovery. Runbooks can be especially well-suited to genera...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/2.0/way/principles/governance-maintainability/offer-golden-paths.md
[grammar] ~12-~12: Ensure spelling is correct
Context: ...em) back in 2020 and remains popular to today. It works because it aligns incentives....
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~12-~12: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ... drive adoption. Application developers want to minimize their responsibilities so they...
(REP_WANT_TO_VB)
docs/2.0/way/intro/welcome.md
[grammar] ~39-~39: Use a hyphen to join words.
Context: ... Makers - We've created leading open source DevOps tooling like [OpenTofu](ht...
(QB_NEW_EN_HYPHEN)
docs/2.0/way/why/maintainability.md
[style] ~21-~21: Consider using a more concise synonym.
Context: ...the infrastructure world, debt takes on a variety of forms: - Drift - Your infrastructu...
(A_VARIETY_OF)
[style] ~26-~26: ‘many different ways’ might be wordy. Consider a shorter alternative.
Context: ...organization solves the same problem in many different ways We pay off infrastructure debt with _r...
(EN_WORDINESS_PREMIUM_MANY_DIFFERENT_WAYS)
docs/2.0/way/resources/glossary.md
[style] ~29-~29: Consider using a different verb to strengthen your wording.
Context: ...orms and tooling | | Primary Goal | Make their team ship faster | Make all teams ship faster with less ...
(MAKE_XXX_FASTER)
[style] ~37-~37: This phrase is redundant. Consider writing “components” or “parts”.
Context: ...any's infrastructure is made up of many component parts. We call the most basic component part ...
(COMPONENT_PART)
[style] ~37-~37: This phrase is redundant. Consider writing “components” or “part”.
Context: ...component parts. We call the most basic component part a unit of infrastructure or just **...
(COMPONENT_PART)
[grammar] ~37-~37: Use a hyphen to join words.
Context: ...rm module, one "unit." In fact, our open source IaC orchestrator [Terragrunt](htt...
(QB_NEW_EN_HYPHEN)
docs/2.0/way/solution/platform/deploy/catalog.md
[grammar] ~58-~58: Use a hyphen to join words.
Context: ...e a git repository. :::info In our open source tool, Terragrunt, we expose a [te...
(QB_NEW_EN_HYPHEN)
docs/2.0/way/solution/patterns/infrastructure-modules/categories.md
[style] ~10-~10: This phrase is redundant. Consider using “subject” to avoid wordiness.
Context: ...odules. Each category has one or more subject matter expertise topics (SME topics). Each S...
(SUBJECT_MATTER)
[grammar] ~70-~70: Ensure spelling is correct
Context: ...RedShift) - Vector databases (Pgvector, Pinecon, Amazon OpenSearch) This covers AI mod...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/2.0/way/solution/patterns/good-patterns.md
[grammar] ~159-~159: Use a hyphen to join words.
Context: ...runtwork subject matter expert, and peer reviewed by other Gruntwork subject matt...
(QB_NEW_EN_HYPHEN)
docs/2.0/way/principles/technical-foundations/define-all-live-infrastructure-as-pattern-instances.md
[style] ~15-~15: Consider a more expressive alternative.
Context: ...at pattern into live infrastructure. To do that, we need a different construct. C...
(DO_ACHIEVE)
[style] ~23-~23: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... want to replace a deprecated resource. Or you may want to define a [Terragrunt St...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/2.0/way/principles/developer-experience/enable-developer-self-service.md
[style] ~18-~18: To elevate your writing, try using a synonym here.
Context: ...lf-service is highly valuable, but also hard to get right.
(HARD_TO)
docs/2.0/way/solution/patterns/overview.md
[style] ~27-~27: This phrase is redundant. Consider using “subject” to avoid wordiness.
Context: ...**_ Any DevOps challenge that requires subject matter expertise can be captured as a pattern....
(SUBJECT_MATTER)
[style] ~27-~27: Consider removing “of” to be more concise
Context: ... be captured as a pattern. For example, all of the following are common DevOps problems th...
(ALL_OF_THE)
[style] ~27-~27: This phrase is redundant. Consider using “subject” to avoid wordiness.
Context: ...ps problems that require some degree of subject matter expertise to solve: - Building a stand...
(SUBJECT_MATTER)
[style] ~39-~39: This phrasing can be wordy, so consider using a more descriptive and concise alternative.
Context: ...t DevOps is "broad and shallow," and as you can see in the list above, patterns can indeed spa...
(AS_YOU_CAN_SEE)
[style] ~41-~41: This phrase can be considered informal. To elevate your writing, consider using a more professional alternative.
Context: ... indeed span a wide range of areas. We talk about patterns as a first-class concept becau...
(TALK_ABOUT_DISCUSS)
docs/2.0/way/intro/share-your-feedback.md
[style] ~8-~8: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...ons - But maybe your mileage varies, or maybe we got it wrong. If so, tell us! - To g...
(REP_MAYBE)
[style] ~9-~9: Try using a synonym here to strengthen your writing.
Context: ...e we got it wrong. If so, tell us! - To give feedback, go to https://github.com/grun...
(GIVE_PROVIDE)
docs/2.0/way/why/governance.mdx
[style] ~11-~11: To elevate your writing, try using a synonym here.
Context: ...ely, the goal is to make non-compliance hard to do rather than easy to do. ## What ...
(HARD_TO)
[grammar] ~17-~17: Use a hyphen to join words.
Context: ...hemselves a few key questions: - Cost effectiveness - Can you afford the inf...
(QB_NEW_EN_HYPHEN)
[style] ~80-~80: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...ands. At the same time, governance has a very large surface area and you can easily overwhe...
(EN_WEAK_ADJECTIVE)
docs/2.0/way/solution/platform/deploy/runbooks.md
[style] ~67-~67: This phrase is redundant. Consider using “subject” to avoid wordiness.
Context: ... the user about this particular area of subject matter expertise, intermixing documentation an...
(SUBJECT_MATTER)
[grammar] ~130-~130: Use a hyphen to join words.
Context: ...e). :::info Gruntwork maintains an open source template generator built speciall...
(QB_NEW_EN_HYPHEN)
[grammar] ~135-~135: Ensure spelling is correct
Context: ...te, a secrets manager, or a third-party cool. The primary limitation of the infrast...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~150-~150: Use a hyphen to join words.
Context: ...or. :::info Gruntwork maintains an open source tool called [Gruntwork Runbooks](...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.18.1)
docs/2.0/way/solution/platform/operate/unit-browser.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/why/overview.md
10-10: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
docs/2.0/way/solution/platform/maintain/importer.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/resources/glossary.md
9-9: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
docs/2.0/way/solution/platform/deploy/catalog.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/solution/platform/maintain/iac-updater.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/solution/platform/maintain/scorecard.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/intro/share-your-feedback.md
9-9: Bare URL used
(MD034, no-bare-urls)
docs/2.0/way/solution/platform/maintain/drift-detector.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/solution/platform/deploy/pipelines.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/solution/platform/deploy/runbooks.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
130-130: Bare URL used
(MD034, no-bare-urls)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Cursor Bugbot
- GitHub Check: Validate generated content
🔇 Additional comments (39)
docs/2.0/way/solution/interfaces/_category_.json (1)
1-5: LGTM! The category descriptor is properly structured and aligns with the documentation organization for the Interfaces section.docs/2.0/way/principles/technical-foundations/use-gitops.md (1)
1-16: LGTM! The GitOps documentation is well-structured and clearly explains the concept in the context of developer platforms. The cross-reference link to the pipelines component is properly formatted and contextually relevant.docs/2.0/way/solution/platform/deploy/_category_.json (1)
1-6: LGTM! The category descriptor is properly structured with thecollapsed: trueflag, which appropriately collapses the Deploy Infrastructure sub-section in the sidebar navigation.docs/2.0/way/principles/core-philosophy/_category_.json (1)
1-5: LGTM! The category descriptor properly establishes the Core Philosophy section with appropriate positioning in the Principles hierarchy.src/css/custom.css (1)
744-748: LGTM! The CSS rules properly target the way-top-level-item class using dual selectors to accommodate potential markup variations. This styling complements the className addition in the category descriptors and effectively highlights top-level sidebar items.docs/2.0/way/principles/_category_.json (1)
1-5: LGTM! The category descriptor includes theclassName: "way-top-level-item"which correctly connects to the CSS styling added in the custom stylesheet, ensuring the Principles section is appropriately highlighted in the sidebar.docs/2.0/way/intro/_category_.json (1)
1-6: LGTM!The category metadata is correctly structured for Docusaurus with appropriate label, position, and className for styling integration.
sidebars/way.js (1)
1-9: LGTM!The sidebar configuration correctly uses Docusaurus's autogenerated type to build the sidebar from the
2.0/waydirectory structure, and properly exports it for consumption by the main sidebars configuration.docs/2.0/way/solution/platform/_category_.json (1)
1-4: LGTM!The category configuration is properly structured and follows Docusaurus conventions.
docs/2.0/way/solution/patterns/_category_.json (1)
1-4: LGTM!The category configuration is clean and follows the established pattern.
docs/2.0/way/solution/platform/maintain/_category_.json (1)
1-5: LGTM!The category configuration correctly includes the
collapsedproperty for sidebar behavior. The structure is consistent with other collapsible categories.docs/2.0/way/solution/platform/operate/_category_.json (1)
1-5: LGTM!The category configuration is correctly structured with appropriate positioning and collapsed behavior.
docs/2.0/way/principles/governance-maintainability/_category_.json (1)
1-4: LGTM!The category configuration is properly formatted and the label clearly conveys the section purpose.
docs/2.0/way/solution/_category_.json (1)
1-5: LGTM!The category configuration correctly uses the
way-top-level-itemclassName for consistent styling across the Way documentation sections.docusaurus.config.js (1)
261-265: Document verified and properly configured.The file
docs/2.0/way/intro/welcome.mdexists and contains the expected content with correct frontmatter (title and sidebar_position). The navbar configuration reference to this document is valid and the internal links are properly formatted.docs/2.0/way/authorship.md (1)
1-10: Internal link verified.The link to the feedback page at
/2.0/way/intro/share-your-feedbackcorrectly points to an existing document. The code and documentation are in order.docs/2.0/way/principles/developer-experience/_category_.json (1)
1-4: Good structure for the navigation hierarchy.This category metadata is correctly positioned and will create a clean navigation structure for the Developer Experience principles section.
docs/2.0/way/intro/how-to-use-this.md (1)
1-30: Well-structured introduction to the framework.Clear explanations of the big picture and the two usage modes. The internal links are properly formatted and the progression of ideas flows naturally. This is a good entry point for readers after the welcome page.
docs/2.0/way/intro/welcome.md (1)
1-44: Compelling introduction to Gruntwork's platform expertise.Strong positioning with clear credibility markers (authors, makers, experts). The three pillars effectively communicate Gruntwork's track record. Good call-to-action flow leading into the next section.
docs/2.0/way/why/_category_.json (1)
1-5: Clean category metadata with semantic CSS class.Good use of the
classNamefield to mark this as a top-level item, enabling consistent styling across the Way navigation structure.docs/2.0/way/solution/patterns/infrastructure-modules/_category_.json (1)
1-4: Straightforward category metadata for infrastructure modules.Properly positioned in the patterns hierarchy.
docs/2.0/way/solution/patterns/types.md (1)
1-80: Comprehensive and well-organized breakdown of pattern types.Clear examples for each category, helpful hierarchy illustration, and good use of the info callout to emphasize the most common type. The interrelationships section (lines 73–75) is particularly valuable for readers trying to understand how different pattern types compose.
docs/2.0/way/solution/platform/maintain/iac-updater.md (1)
1-22: Clear, concise overview of the IaC Updater feature.Effectively communicates the problem it solves, the value it provides, and the concrete capabilities. Good structure for this feature documentation.
docs/2.0/way/principles/core-philosophy/the-platform-is-a-balancing-act.md (1)
1-19: LGTM!This page effectively frames the three competing platform concerns and emphasizes that balance depends on organizational maturity. The writing is clear, and the internal links are well-placed. No issues to flag.
docs/2.0/way/principles/developer-experience/make-good-practices-the-default.md (1)
1-11: LGTM!Concise and punchy—exactly what a principle page should be. The point about embedding compliance and security "for free" via patterns is clear and compelling.
docs/2.0/way/solution/platform/operate/dashboards.md (1)
1-22: LGTM!Well-structured overview of dashboards with clear sections on why they matter and what they enable. Consistent formatting with other solution pages, and the message is straightforward and practical.
docs/2.0/way/principles/overview.md (1)
1-41: LGTM!This hub page is well-organized and provides excellent navigation into the four principle categories. The intro is welcoming, each section is clearly labeled, and the linked principles are properly formatted and accessible. Great foundation for the principles documentation.
sidebars.js (1)
17-17: LGTM!The waySidebar integration follows the established pattern for sidebar configuration. The import and export are correctly structured.
Also applies to: 28-28
docs/2.0/way/solution/patterns/infrastructure-modules/overview.md (1)
1-11: LGTM!This overview page provides a clear introduction to infrastructure modules and effectively signposts the reader to more detailed content. The structure and links are well-organized.
docs/2.0/way/resources/sources.md (1)
1-56: LGTM!This sources page is well-structured with clear categorization and consistent formatting. The inclusion of the "Proper attribution" section demonstrates good documentation hygiene and academic integrity.
docs/2.0/way/why/governance.mdx (1)
1-126: LGTM!This governance documentation is comprehensive and well-structured, covering the what, why, how, and measurement aspects effectively. The metrics framework (state + flow metrics) is particularly valuable.
docs/2.0/way/principles/developer-experience/enable-developer-self-service.md (1)
1-19: LGTM!This page provides a clear, concise definition of developer self-service with well-integrated links to the necessary platform capabilities. The structure effectively guides readers to deeper content.
docs/2.0/way/solution/platform/operate/registry.md (1)
1-22: LGTM!This Registry documentation is clear and well-organized. The three-part structure (definition, why it matters, what it enables) makes the concept easy to understand and the benefits clear.
docs/2.0/way/principles/core-philosophy/your-developer-platform-is-a-product.md (1)
1-18: LGTM!This page effectively uses the startup/product metaphor to frame the developer platform concept. The parallel bullet structure with "Products..." creates a clear, memorable framework that readers can easily follow.
docs/2.0/way/principles/developer-experience/shift-left.md (1)
1-19: Content is clear and well-structured.The explanation of shift-left avoids unnecessary jargon while remaining technically accurate. The progression from problem statement to practical tools is effective. Based on learnings, this aligns well with guidance to simplify DevOps concepts for clarity.
docs/2.0/way/solution/platform/overview.md (1)
1-44: Excellent structural overview with clear categorization.The three-part framework for platform components is well-organized, each category has concrete examples, and the "Build vs buy" section adds practical value. Cross-links align with the broader documentation structure being introduced in this PR.
docs/2.0/way/principles/failure-modes.md (1)
1-67: Well-structured guidance on platform pitfalls and prevention.The four failure modes are presented clearly with consistent structure and practical advice. The cross-references to core principles and components reinforce the broader Way framework effectively.
docs/2.0/way/principles/governance-maintainability/guardrails-over-gates.md (1)
1-25: LGTM!This page clearly explains the concept and its role in balancing governance and velocity. The structure and cross-references are well-organized.
docs/2.0/way/resources/_category_.json (1)
1-10: LGTM!Valid structure and metadata configuration for the Resources section.
docs/2.0/way/principles/governance-maintainability/offer-golden-paths.md
Outdated
Show resolved
Hide resolved
docs/2.0/way/principles/technical-foundations/represent-all-patterns-as-code.md
Outdated
Show resolved
Hide resolved
|
|
||
| Here's the Gruntwork take on the most common terms we encounter in Platform Engineering and DevOps: | ||
|
|
||
| ### Developer Platform |
There was a problem hiding this comment.
Fix heading level hierarchy.
The heading jumps from h1 (line 5) to h3 (line 9), skipping h2. Markdown heading levels should increment by one level at a time for proper document structure and accessibility.
Apply this diff:
-### Developer Platform
+## Developer PlatformAnd apply the same fix to all other h3 headings in this file (lines 13, 17, 21, 31, 35, 39).
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Developer Platform | |
| ## Developer Platform |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
9-9: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
In docs/2.0/way/resources/glossary.md around lines 9 to 9, the heading
"Developer Platform" is an h3 while the document previously used h1, so change
that h3 to h2 to restore proper incremental heading hierarchy; also update the
other h3 headings at lines 13, 17, 21, 31, 35, and 39 to h2 so all headings
increment by one level from the h1 and maintain consistent, accessible
structure.
docs/2.0/way/solution/patterns/infrastructure-modules/categories.md
Outdated
Show resolved
Hide resolved
| # Importer | ||
|
|
||
| **Import non-codified assets** |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Convert bold emphasis to a proper heading to satisfy markdown linting.
Line 8 uses bold emphasis (**Import non-codified assets**) instead of a Markdown heading. This violates the MD036 linting rule. To match best practices, convert to a heading level or integrate into the main heading.
-# Importer
-
-**Import non-codified assets**
+# Importer: Import non-codified assetsOr keep them separate with a heading:
-**Import non-codified assets**
+## Import non-codified assets📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Importer | |
| **Import non-codified assets** | |
| # Importer: Import non-codified assets |
| # Importer | |
| **Import non-codified assets** | |
| # Importer | |
| ## Import non-codified assets |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In docs/2.0/way/solution/platform/maintain/importer.md around lines 6 to 8, the
line using bold emphasis ("**Import non-codified assets**") should be converted
to a proper Markdown heading to satisfy MD036; replace the bold-only line with
an appropriate heading level (e.g., "## Import non-codified assets" or "###
Import non-codified assets") or merge its content into the existing top-level
heading so the document uses semantic headings rather than bold text.
| # Scorecard | ||
|
|
||
| **Assess standards compliance** |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Convert bold emphasis to a proper heading to satisfy markdown linting.
Line 8 uses bold emphasis (**Assess standards compliance**) instead of a Markdown heading. This violates the MD036 linting rule. Consider converting it to a heading level like ## Assess standards compliance or making it part of the narrative.
-# Scorecard
-
-**Assess standards compliance**
+# Scorecard: Assess standards complianceOr keep them separate with a heading:
-**Assess standards compliance**
+## Assess standards compliance📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Scorecard | |
| **Assess standards compliance** | |
| # Scorecard | |
| ## Assess standards compliance |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In docs/2.0/way/solution/platform/maintain/scorecard.md around lines 6 to 8, the
line currently uses bold emphasis ("**Assess standards compliance**") which
triggers MD036; replace that bold text with an explicit markdown heading such as
"## Assess standards compliance" (or another appropriate heading level), ensure
surrounding blank lines are correct so the heading renders properly, and keep
any remaining narrative text as normal paragraph content.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/2.0/way/intro/share-your-feedback.md (2)
8-8: Reduce repetitive "maybe" phrasing for variety.The phrase "or maybe we got it wrong" echoes the structure from "maybe your mileage varies" just two sentences earlier. Consider varying the phrasing to improve readability.
You might try:
-But maybe your mileage varies, or maybe we got it wrong. If so, tell us! +But maybe your mileage varies, or perhaps we missed the mark. If so, tell us!
9-9: Consider "provide" instead of "give" for stronger language.Per the static analysis hints, using "provide" rather than "give" can strengthen the phrasing in technical writing.
Apply this minor wording improvement:
-To give feedback, go to https://github.com/gruntwork-io/docs and create a GitHub Issue or Pull Request. Alternatively click on the "Edit this page" link at the bottom of each page. +To provide feedback, go to https://github.com/gruntwork-io/docs and create a GitHub Issue or Pull Request. Alternatively click on the "Edit this page" link at the bottom of each page.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/2.0/way/intro/share-your-feedback.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/2.0/way/intro/share-your-feedback.md
[style] ~8-~8: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...ons - But maybe your mileage varies, or maybe we got it wrong. If so, tell us! - To g...
(REP_MAYBE)
[style] ~9-~9: Try using a synonym here to strengthen your writing.
Context: ...e we got it wrong. If so, tell us! - To give feedback, go to https://github.com/grun...
(GIVE_PROVIDE)
🪛 markdownlint-cli2 (0.18.1)
docs/2.0/way/intro/share-your-feedback.md
9-9: Bare URL used
(MD034, no-bare-urls)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)
- GitHub Check: Pull Request has non-contributor approval
- GitHub Check: Pull Request has non-contributor approval
- GitHub Check: Cursor Bugbot
- GitHub Check: validate_build
- GitHub Check: Pull Request has non-contributor approval
- GitHub Check: Pull Request has non-contributor approval
- GitHub Check: Validate generated content
| - This framework is useful because it's opinionated. | ||
| - Our opinions are based on nearly a decade of experience across hundreds of customers and thousand of customer conversations | ||
| - But maybe your mileage varies, or maybe we got it wrong. If so, tell us! | ||
| - To give feedback, go to https://github.com/gruntwork-io/docs and create a GitHub Issue or Pull Request. Alternatively click on the "Edit this page" link at the bottom of each page. |
There was a problem hiding this comment.
Format the bare URL as a proper Markdown link.
The bare URL violates MD034 (no-bare-urls). Wrap it in Markdown link syntax to improve readability and maintainability.
Apply this diff to fix the bare URL:
-To give feedback, go to https://github.com/gruntwork-io/docs and create a GitHub Issue or Pull Request. Alternatively click on the "Edit this page" link at the bottom of each page.
+To give feedback, go to [gruntwork-io/docs](https://github.com/gruntwork-io/docs) and create a GitHub Issue or Pull Request. Alternatively click on the "Edit this page" link at the bottom of each page.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - To give feedback, go to https://github.com/gruntwork-io/docs and create a GitHub Issue or Pull Request. Alternatively click on the "Edit this page" link at the bottom of each page. | |
| - To give feedback, go to [gruntwork-io/docs](https://github.com/gruntwork-io/docs) and create a GitHub Issue or Pull Request. Alternatively click on the "Edit this page" link at the bottom of each page. |
🧰 Tools
🪛 LanguageTool
[style] ~9-~9: Try using a synonym here to strengthen your writing.
Context: ...e we got it wrong. If so, tell us! - To give feedback, go to https://github.com/grun...
(GIVE_PROVIDE)
🪛 markdownlint-cli2 (0.18.1)
9-9: Bare URL used
(MD034, no-bare-urls)
🤖 Prompt for AI Agents
In docs/2.0/way/intro/share-your-feedback.md around line 9, the bare URL
"https://github.com/gruntwork-io/docs" should be converted to a Markdown link;
replace the raw URL with inline link syntax (e.g.,
[gruntwork-io/docs](https://github.com/gruntwork-io/docs)) so the sentence reads
with a proper link and retains the rest of the text unchanged.
All typo fixes. Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (2)
docs/2.0/way/resources/glossary.md (1)
9-9: Fix heading level hierarchy.The document uses an h1 for the main title (line 5) but then jumps to h3 for all section headings, skipping h2. Markdown headings should increment by one level at a time for proper document structure, accessibility, and linting compliance.
Change all h3 headings to h2:
-### Developer Platform +## Developer Platform-### DevOps Engineer +## DevOps Engineer-### Platform Engineer +## Platform Engineer-### DevOps vs. Platform Engineer +## DevOps vs. Platform Engineer-### DevOps bankruptcy +## DevOps bankruptcy-### Unit +## Unit-### Stack +## StackAlso applies to: 13-13, 17-17, 21-21, 31-31, 35-35, 39-39
docs/2.0/way/solution/platform/deploy/runbooks.md (1)
148-151: Fix hyphenation: "open source" → "open-source" at line 150.Line 150 uses "open source" as a compound adjective, which should be hyphenated to match the correction already applied at line 130 elsewhere in the file.
Apply this diff:
-Gruntwork maintains an open source tool called [Gruntwork Runbooks](https://runbooks.gruntwork.io/) that is based on all the insights and philosophy that we capture here. Check it out! +Gruntwork maintains an open-source tool called [Gruntwork Runbooks](https://runbooks.gruntwork.io/) that is based on all the insights and philosophy that we capture here. Check it out!
🧹 Nitpick comments (2)
docs/2.0/way/solution/patterns/infrastructure-modules/categories.md (1)
10-10: Minor style refinement: simplify "subject matter expertise topics" phrasing.The phrase "subject matter expertise topics (SME topics)" is slightly verbose. Consider simplifying to just "subject expertise topics" or "expertise topics" to tighten the prose while keeping the same meaning and acronym.
-Each category has one or more **subject matter expertise topics (SME topics)**. Each SME topic has one or more infrastructure modules. +Each category has one or more **subject expertise topics (SME topics)**. Each SME topic has one or more infrastructure modules.docs/2.0/way/solution/platform/deploy/runbooks.md (1)
49-144: Well-structured comparison of runbook implementation options. The progression from static documentation through to first-class runbooks is logical, and code examples are clear. Previous typos and formatting issues (lines 68, 130, 135) have been corrected.One optional refactor: Line 67 includes "subject matter expertise," which the linter flags as potentially redundant. Consider whether shortening to "subject" would improve conciseness, though the current phrasing is idiomatic and acceptable as-is.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
docs/2.0/way/principles/governance-maintainability/offer-golden-paths.md(1 hunks)docs/2.0/way/principles/technical-foundations/represent-all-patterns-as-code.md(1 hunks)docs/2.0/way/resources/glossary.md(1 hunks)docs/2.0/way/solution/patterns/infrastructure-modules/categories.md(1 hunks)docs/2.0/way/solution/patterns/overview.md(1 hunks)docs/2.0/way/solution/platform/deploy/runbooks.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/2.0/way/principles/governance-maintainability/offer-golden-paths.md
🧰 Additional context used
🪛 LanguageTool
docs/2.0/way/principles/technical-foundations/represent-all-patterns-as-code.md
[style] ~25-~25: To elevate your writing, try using a synonym here.
Context: ...id the original configuration, and it's hard to track or know about any updates to t...
(HARD_TO)
[grammar] ~34-~34: Use a hyphen to join words.
Context: ... be reverted if needed. Code can be peer reviewed, and automated tests can run to...
(QB_NEW_EN_HYPHEN)
[style] ~49-~49: ‘emergency situations’ might be wordy. Consider a shorter alternative.
Context: ... code does take more time. Sometimes in emergency situations, engineers might need to optimize for s...
(EN_WORDINESS_PREMIUM_EMERGENCY_SITUATIONS)
docs/2.0/way/solution/patterns/infrastructure-modules/categories.md
[style] ~10-~10: This phrase is redundant. Consider using “subject” to avoid wordiness.
Context: ...odules. Each category has one or more subject matter expertise topics (SME topics). Each S...
(SUBJECT_MATTER)
docs/2.0/way/resources/glossary.md
[style] ~29-~29: Consider using a different verb to strengthen your wording.
Context: ...orms and tooling | | Primary Goal | Make their team ship faster | Make all teams ship faster with less ...
(MAKE_XXX_FASTER)
[style] ~37-~37: This phrase is redundant. Consider writing “components” or “parts”.
Context: ...any's infrastructure is made up of many component parts. We call the most basic component part ...
(COMPONENT_PART)
[style] ~37-~37: This phrase is redundant. Consider writing “components” or “part”.
Context: ...component parts. We call the most basic component part a unit of infrastructure or just **...
(COMPONENT_PART)
[grammar] ~37-~37: Use a hyphen to join words.
Context: ...rm module, one "unit." In fact, our open source IaC orchestrator [Terragrunt](htt...
(QB_NEW_EN_HYPHEN)
docs/2.0/way/solution/patterns/overview.md
[style] ~25-~25: This phrase is redundant. Consider using “subject” to avoid wordiness.
Context: ...**_ Any DevOps challenge that requires subject matter expertise can be captured as a pattern....
(SUBJECT_MATTER)
[style] ~25-~25: Consider removing “of” to be more concise
Context: ... be captured as a pattern. For example, all of the following are common DevOps problems th...
(ALL_OF_THE)
[style] ~25-~25: This phrase is redundant. Consider using “subject” to avoid wordiness.
Context: ...ps problems that require some degree of subject matter expertise to solve: - Building a stand...
(SUBJECT_MATTER)
[style] ~37-~37: This phrasing can be wordy, so consider using a more descriptive and concise alternative.
Context: ...t DevOps is "broad and shallow," and as you can see in the list above, patterns can indeed spa...
(AS_YOU_CAN_SEE)
[style] ~39-~39: This phrase can be considered informal. To elevate your writing, consider using a more professional alternative.
Context: ... indeed span a wide range of areas. We talk about patterns as a first-class concept becau...
(TALK_ABOUT_DISCUSS)
docs/2.0/way/solution/platform/deploy/runbooks.md
[style] ~67-~67: This phrase is redundant. Consider using “subject” to avoid wordiness.
Context: ... the user about this particular area of subject matter expertise, intermixing documentation an...
(SUBJECT_MATTER)
[grammar] ~150-~150: Use a hyphen to join words.
Context: ...or. :::info Gruntwork maintains an open source tool called [Gruntwork Runbooks](...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.18.1)
docs/2.0/way/resources/glossary.md
9-9: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
docs/2.0/way/solution/platform/deploy/runbooks.md
59-59: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)
- GitHub Check: Cursor Bugbot
- GitHub Check: validate_build
- GitHub Check: Pull Request has non-contributor approval
- GitHub Check: Pull Request has non-contributor approval
- GitHub Check: Validate generated content
🔇 Additional comments (5)
docs/2.0/way/solution/patterns/infrastructure-modules/categories.md (1)
1-77: Great documentation structure and content.The file is well-organized with clear hierarchy, helpful examples, and appropriate cross-cloud context notes (lines 31, 59). The categories are logically grouped, and the progression from general (Cloud foundations) to specialized (AI) makes sense. The integration of AWS terminology notes shows thoughtful consideration for your audience.
docs/2.0/way/solution/platform/deploy/runbooks.md (2)
1-11: Clean structure and metadata. The frontmatter and initial heading hierarchy are well-organized and follow documentation conventions.
12-48: Excellent explanation of the problem and solution. The section effectively motivates the runbook concept and clearly establishes the developer self-service workflow. The typo from the previous review ("breath" → "breadth" at line 25) has been corrected.docs/2.0/way/solution/patterns/overview.md (1)
20-20: ✓ Past typo has been fixed.The typo from the earlier review ("bo" → "go") is now corrected. The sentence flows well and the content is clear.
docs/2.0/way/principles/technical-foundations/represent-all-patterns-as-code.md (1)
1-54: ✓ Past formatting issue has been fixed; content is well-structured.The unclosed italic from the earlier review has been resolved. The document effectively explains why patterns should be codified, with clear before/after comparisons and thoughtful caveats about balancing velocity and maintainability. The references to related sections (pre-built patterns, platform balancing act, debt) help orient readers within the broader Gruntwork Way framework.
|
|
||
| Around 2014, these issues reached an inflection point and the idea of infrastructure-as-code was then a major paradigm shift. More than a decade later, we can now generalize the idea of representing all infrastructure as code to the idea that you should **represent all patterns as code,** and then [define all live infrastructure as pattern instances](/2.0/way/principles/technical-foundations/define-all-live-infrastructure-as-pattern-instances). | ||
|
|
||
| Representing patterns as code brings many benefits. To start, when anything is captured as code, it can be stored in version control. That means that every change is now tracked, attributed, and can be reverted if needed. Code can be peer reviewed, and automated tests can run to immediately validate the newly committed code. |
There was a problem hiding this comment.
Fix hyphenation: "peer reviewed" → "peer-reviewed".
When "peer-reviewed" works as a compound modifier, it should be hyphenated. Apply this diff:
-Code can be peer reviewed, and automated tests can run to immediately validate the newly committed code.
+Code can be peer-reviewed, and automated tests can run to immediately validate the newly committed code.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Representing patterns as code brings many benefits. To start, when anything is captured as code, it can be stored in version control. That means that every change is now tracked, attributed, and can be reverted if needed. Code can be peer reviewed, and automated tests can run to immediately validate the newly committed code. | |
| Representing patterns as code brings many benefits. To start, when anything is captured as code, it can be stored in version control. That means that every change is now tracked, attributed, and can be reverted if needed. Code can be peer-reviewed, and automated tests can run to immediately validate the newly committed code. |
🧰 Tools
🪛 LanguageTool
[grammar] ~34-~34: Use a hyphen to join words.
Context: ... be reverted if needed. Code can be peer reviewed, and automated tests can run to...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In
docs/2.0/way/principles/technical-foundations/represent-all-patterns-as-code.md
around line 34, the phrase "peer reviewed" should be hyphenated when used as a
compound modifier; update the text to "peer-reviewed" so the sentence reads
"...Code can be peer-reviewed, and automated tests..." preserving surrounding
punctuation and spacing.
|
|
||
| ### Unit | ||
|
|
||
| Any company's infrastructure is made up of many component parts. We call the most basic component part a **unit of infrastructure** or just **unit** for short. For example, we consider one instance of one OpenTofu/Terraform module, one "unit." In fact, our open source IaC orchestrator [Terragrunt](https://terragrunt.gruntwork.io) uses this exact terminology! |
There was a problem hiding this comment.
Simplify redundant phrasing and add hyphenation.
Line 37 contains redundant phrases and a missing hyphen:
- "component parts" and "component part" are redundant—use "components" or "parts"
- "open source IaC" should be hyphenated as "open-source IaC"
Apply this diff:
-Any company's infrastructure is made up of many component parts. We call the most basic component part a **unit of infrastructure** or just **unit** for short. For example, we consider one instance of one OpenTofu/Terraform module, one "unit." In fact, our open source IaC orchestrator [Terragrunt](https://terragrunt.gruntwork.io) uses this exact terminology!
+Any company's infrastructure is made up of many components. We call the most basic component a **unit of infrastructure** or just **unit** for short. For example, we consider one instance of one OpenTofu/Terraform module, one "unit." In fact, our open-source IaC orchestrator [Terragrunt](https://terragrunt.gruntwork.io) uses this exact terminology!📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Any company's infrastructure is made up of many component parts. We call the most basic component part a **unit of infrastructure** or just **unit** for short. For example, we consider one instance of one OpenTofu/Terraform module, one "unit." In fact, our open source IaC orchestrator [Terragrunt](https://terragrunt.gruntwork.io) uses this exact terminology! | |
| Any company's infrastructure is made up of many components. We call the most basic component a **unit of infrastructure** or just **unit** for short. For example, we consider one instance of one OpenTofu/Terraform module, one "unit." In fact, our open-source IaC orchestrator [Terragrunt](https://terragrunt.gruntwork.io) uses this exact terminology! |
🧰 Tools
🪛 LanguageTool
[style] ~37-~37: This phrase is redundant. Consider writing “components” or “parts”.
Context: ...any's infrastructure is made up of many component parts. We call the most basic component part ...
(COMPONENT_PART)
[style] ~37-~37: This phrase is redundant. Consider writing “components” or “part”.
Context: ...component parts. We call the most basic component part a unit of infrastructure or just **...
(COMPONENT_PART)
[grammar] ~37-~37: Use a hyphen to join words.
Context: ...rm module, one "unit." In fact, our open source IaC orchestrator [Terragrunt](htt...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In docs/2.0/way/resources/glossary.md around line 37, the sentence uses
redundant phrasing ("component parts"/"component part") and misses hyphenation
for "open-source IaC"; rephrase to remove redundancy (e.g., use "components" or
"parts" once), change "unit of infrastructure" phrasing if needed for clarity,
and hyphenate "open-source IaC" so the sentence reads smoothly and concisely
while preserving the example about Terragrunt.
There was a problem hiding this comment.
Actionable comments posted: 10
♻️ Duplicate comments (1)
docs/2.0/way/platform/components/maintain/importer.md (1)
6-8: Convert bold emphasis to a proper Markdown heading (duplicate feedback).This issue was flagged in a previous review but remains unresolved. Line 8 violates the MD036 linting rule by using bold emphasis instead of a semantic heading:
# Importer -**Import non-codified assets** +## Import non-codified assets
🧹 Nitpick comments (35)
docs/2.0/way/why/governance.mdx (2)
17-17: Hyphenate compound adjectives."Cost effectiveness" and "Standards adherence" should be hyphenated when used as adjectives preceding nouns.
- **Cost effectiveness** - Can you afford the infrastructure you're deploying? + **Cost-effectiveness** - Can you afford the infrastructure you're deploying?
80-80: Consider a more specific word than "very large."Per style guidance, "very large" is an over-used intensifier. Consider rephrasing to be more precise about what makes governance's surface area challenging.
- At the same time, governance has a very large surface area and you can easily overwhelm yourself with metrics. + At the same time, governance has an expansive surface area and you can easily overwhelm yourself with metrics.docs/2.0/way/principles/governance-maintainability/guardrails-over-gates.md (1)
14-14: Use consistent spelling throughout: "judgment" vs "judgement."The document mixes American English ("judgment" on line 14) and British English ("judgement"). Choose one variant and apply it consistently. American English "judgment" is standard in tech documentation.
- A **guardrail** is any automated rule or policy that checks infrastructure operations or status against your standards. When you create a guardrail, you are reducing that manual human judgment down to a narrowly scoped rule that systematically renders an opinion on a well-defined situation. + A **guardrail** is any automated rule or policy that checks infrastructure operations or status against your standards. When you create a guardrail, you are reducing that manual human judgment down to a narrowly scoped rule that systematically renders a judgment on a well-defined situation.docs/2.0/way/principles/failure-modes.md (1)
63-63: Hyphenate "open-source" when used as a compound adjective."Open-source" should be hyphenated when modifying a noun directly.
- First, as platform engineers, look for pre-built, battle-tested patterns wherever possible. These could be open source modules, or commercial module catalogs like the [Gruntwork AWS IaC Library](https://docs.gruntwork.io/2.0/docs/library/concepts/overview). + First, as platform engineers, look for pre-built, battle-tested patterns wherever possible. These could be open-source modules, or commercial module catalogs like the [Gruntwork AWS IaC Library](https://docs.gruntwork.io/2.0/docs/library/concepts/overview).docs/2.0/way/platform/patterns/where-to-store-them.md (1)
13-13: Simplify "with respect to" for clarity."With respect to" is wordy. Consider "for" or restructuring the sentence.
- **Software artifact repository.** Tools like [Artifactory](https://jfrog.com/artifactory/) or [Sonatype Nexus Repository](https://www.sonatype.com/products/sonatype-nexus-repository) can _store_ all the different pattern types, but they often have limited _functionality_ with respect to these infrastructure-as-code pattern types. + **Software artifact repository.** Tools like [Artifactory](https://jfrog.com/artifactory/) or [Sonatype Nexus Repository](https://www.sonatype.com/products/sonatype-nexus-repository) can _store_ all the different pattern types, but they often have limited _functionality_ for infrastructure-as-code patterns.docs/2.0/way/platform/components/deploy/pipelines.md (1)
8-8: Use proper heading syntax instead of emphasis.Line 8 uses bold emphasis (
**...**) as a heading. Use markdown heading syntax (###) instead to maintain proper document structure for accessibility and navigation.- **How you deploy infrastructure changes** + ### How you deploy infrastructure changesdocs/2.0/way/platform/components/deploy/catalog.md (2)
8-8: Use proper heading syntax instead of emphasis.Line 8 uses bold emphasis (
**...**) as a heading. Use markdown heading syntax (###) instead to maintain proper document structure for accessibility and navigation.- **Where you store your organization's patterns** + ### Where you store your organization's patterns
58-58: Hyphenate "open-source" when used as a compound adjective."Open-source" should be hyphenated when modifying a noun directly.
- :::info - In our open source tool, Terragrunt, we expose a [terragrunt catalog](https://terragrunt.gruntwork.io/docs/features/catalog/) command that presents a Terminal UI to select the desired module from a specified set of git repos. - ::: + :::info + In our open-source tool, Terragrunt, we expose a [terragrunt catalog](https://terragrunt.gruntwork.io/docs/features/catalog/) command that presents a Terminal UI to select the desired module from a specified set of git repos. + :::docs/2.0/way/platform/interfaces/overview.md (1)
10-24: Consider varying introductory phrasing for better prose flow.The sections for Web UI (line 12), CLI (line 16), API (line 20), and AI/MCP (line 24) all open with similar "X works well when..." constructions. While clear, varying the phrasing would improve readability.
Example revision for the CLI section:
- ## CLI - - The CLI works well when developers want to interact with your platform directly from their terminal... + ## CLI + + Developers who spend most of their day in the terminal benefit from CLI access to your platform. Direct interaction enables speed, scriptability...docs/2.0/way/platform/components/overview.md (1)
52-54: Vary sentence openings to improve prose flow.Lines 52–54 repeat "You can" at the beginning of successive sentences. Restructuring some sentences improves readability:
## Build vs buy - You can choose to build or buy most of these components. You can build some and buy others. You can also choose to optimize for "best of breed" (the best individual component) or "best of suite" (the best combination of components), or mix and match build and buy to suit your needs. + Most components can be built or purchased. You can combine build and buy approaches or optimize for "best of breed" (the best individual component) or "best of suite" (the best combination of components) to suit your needs.docs/2.0/way/platform/patterns/overview.md (1)
25-25: Reduce wordiness and repetition in this paragraph.The phrase "subject matter expertise" appears three times in quick succession (lines 25–26), and "all of the following" is flagged as unnecessarily wordy.
Apply this diff to improve clarity:
- Any DevOps challenge that requires subject matter expertise can be captured as a pattern. For example, all of the following are common DevOps problems that require some degree of subject matter expertise to solve: + Any DevOps challenge requiring subject matter expertise can be captured as a pattern. For example, these common DevOps problems exemplify this:docs/2.0/way/why/overview.md (2)
40-40: Simplify wordy phrasing.Line 40 uses "many different ways" which is flagged as unnecessarily wordy. Simplify to "various ways" or "many ways":
- - **Non-standardization** - Your organization solves the same problem in many different ways + - **Non-standardization** - Your organization solves the same problem in various ways
52-52: Remove redundant phrasing.Line 52 contains "this moment in time," which is redundant. Simplify to "this moment" or "now":
- The art of platform engineering is finding the right balance among velocity, governance, and maintainability for your organization at this moment in time, and adjusting that balance as your needs evolve. + The art of platform engineering is finding the right balance among velocity, governance, and maintainability for your organization right now, and adjusting that balance as your needs evolve.docs/2.0/way/why/maintainability.md (2)
1-3: Consider adding an explicit document ID to front matter.The file lacks an explicit
idfield in the front matter. While Docusaurus auto-generates IDs from filenames, explicitly settingid: maintainabilityaligns with best practices used elsewhere in the repository and provides clarity.As per coding guidelines (from prior learnings in this repo):
--- sidebar_position: 4 +id: maintainability ---
19-26: Minor wordiness in the debt analogy section.The phrasing on lines 21 and 26 could be tightened for clarity:
- Line 21: "takes on a variety of forms" → "comes in several forms"
- Line 26: "solves the same problem in many different ways" → "solves the same problem in multiple ways"
These are minor style tweaks that improve conciseness.
docs/2.0/way/intro/welcome.md (2)
1-4: Add explicit document ID to front matter.Per best practices used in this repository (from prior PR guidance), add an explicit
idfield that matches the filename:--- title: Welcome! +id: welcome sidebar_position: 1 ---Based on learnings from previous reviews in this repo.
38-40: Use hyphenated form of "open-source" before the noun.On line 39, when "open source" appears before the noun "DevOps tooling," it should be hyphenated as a compound adjective. Change to:
-* **Makers** - We've created leading open source DevOps tooling like [OpenTofu](ht... +* **Makers** - We've created leading open-source DevOps tooling like [OpenTofu](ht...docs/2.0/way/principles/developer-experience/enable-developer-self-service.md (1)
1-4: Add explicit document ID to front matter.For consistency with best practices, add:
--- sidebar_position: 2 title: Enable developer self-service +id: enable-developer-self-service ---docs/2.0/way/platform/components/maintain/iac-updater.md (1)
1-4: Add explicit document ID to front matter.--- sidebar_position: 2 title: IaC Updater +id: iac-updater ---docs/2.0/way/platform/patterns/infrastructure-modules/overview.md (1)
1-4: Add explicit document ID to front matter.--- sidebar_position: 1 title: Overview +id: overview ---docs/2.0/way/platform/components/maintain/importer.md (1)
1-4: Add explicit document ID to front matter.--- sidebar_position: 4 title: Importer +id: importer ---docs/2.0/way/platform/patterns/types.md (2)
58-67: Consider reordering to avoid repetitive sentence openings in the Runbooks section.Lines 60-62 show repetitive sentence structure starting with similar words. Consider restructuring:
Runbooks are step-by-step (and sometimes interactive) operational procedures for infrastructure tasks such as incident response, guided code generation, troubleshooting, and recovery. -Runbooks can be especially well-suited to generating code based on [templates](#templates). +They can be especially well-suited to generating code based on [templates](#templates), or combined with [policies](#policies) to enforce operational standards.
1-4: Add explicit document ID to front matter.--- sidebar_position: 2 title: Types +id: types ---docs/2.0/way/platform/components/operate/registry.md (1)
1-4: Add explicit document ID to front matter.--- sidebar_position: 2 title: Registry +id: registry ---docs/2.0/way/principles/developer-experience/pre-built-patterns-are-your-leverage.md (1)
22-22: Apply hyphen to compound adjective "in-house".Line 22 should read "authored in-house" rather than "authored inhouse."
-Patterns can be authored inhouse, or "vendored" from open source or commercial pattern libraries (like [Gruntwork IaC Library](https://docs.gruntwork.io/2.0/docs/library/concepts/overview)). +Patterns can be authored in-house, or "vendored" from open source or commercial pattern libraries (like [Gruntwork IaC Library](https://docs.gruntwork.io/2.0/docs/library/concepts/overview)).docs/2.0/way/intro/who-this-is-for.md (1)
20-22: Reduce redundancy by simplifying "component parts."Lines 20 and 22 use the phrase "component parts," which is flagged as redundant. Consider using either "components" or "parts" alone to improve conciseness.
-Actually, to be more precise, you will build maturity separately in your [patterns](/2.0/way/platform/patterns/overview), [platform components](/2.0/way/platform/components/overview), and [interfaces](/2.0/way/platform/interfaces/overview). Your collective maturity level for the "developer platform" is really just the collection of maturity levels for its component parts. +Actually, to be more precise, you will build maturity separately in your [patterns](/2.0/way/platform/patterns/overview), [platform components](/2.0/way/platform/components/overview), and [interfaces](/2.0/way/platform/interfaces/overview). Your collective maturity level for the "developer platform" is really just the collection of maturity levels for its components.-In general, the component parts track these maturity levels: +In general, the components track these maturity levels:docs/2.0/way/platform/patterns/good-patterns.md (1)
159-159: Apply hyphen to compound modifier "peer-reviewed."Line 159 uses "peer reviewed" as a compound modifier and should be hyphenated. Update to:
-It was written by a Gruntwork subject matter expert, and peer reviewed by other Gruntwork subject matter experts, so it is **vetted.** +It was written by a Gruntwork subject matter expert, and peer-reviewed by other Gruntwork subject matter experts, so it is **vetted.**docs/2.0/way/platform/patterns/infrastructure-modules/authoring.md (4)
32-32: Hyphenate "open-source" when used as compound adjective.Line 32 uses "open source" in an adjectival context and should be hyphenated:
-2. **Use open source infrastructure modules** - You find community-authored infrastructure modules that work for your needs, review them, and vet them as an official infrastructure modules for your organization. This gives you low control, but also outsources maintenance to others (low control, high convenience) +2. **Use open-source infrastructure modules** - You find community-authored infrastructure modules that work for your needs, review them, and vet them as an official infrastructure modules for your organization. This gives you low control, but also outsources maintenance to others (low control, high convenience)
40-40: Hyphenate "open-source" consistently in compound adjective contexts.Lines 40 uses "open source" twice as a compound adjective and should be hyphenated:
-2. **Wrapper module** - You write an inhouse module that calls the third-party module. This gives you the ability to customize the third-party module without having to re-implement or maintain it. Users will now directly access this wrapper module. For example, you use an open source AWS Lambda module, but write your own Acme AWS Lambda module that uses the open source AWS Lambda module. +2. **Wrapper module** - You write an inhouse module that calls the third-party module. This gives you the ability to customize the third-party module without having to re-implement or maintain it. Users will now directly access this wrapper module. For example, you use an open-source AWS Lambda module, but write your own Acme AWS Lambda module that uses the open-source AWS Lambda module.
112-112: Hyphenate "open-source" and improve sentence clarity.Line 112 has two issues: (1) "open source" should be hyphenated as a compound adjective, and (2) the phrase can be more concise:
-In our experience, the better option is to deal with empty versions and fewer git repos. Better yet, you can write tooling to automate nearly all aspects of empty versions (like your [IaC updater](/2.0/way/platform/components/maintain/iac-updater)). There's also tooling available to manage many git repos at once (like our open source tool, [git-xargs](https://github.com/gruntwork-io/git-xargs)), but using these can be cumbersome. That's why we recommend fewer git repos at the expense of empty versions, mitigated by tooling. +In our experience, the better option is to deal with empty versions and fewer git repos. Better yet, you can write tooling to automate nearly all aspects of empty versions (like your [IaC updater](/2.0/way/platform/components/maintain/iac-updater)). There's also tooling available to manage many git repos at once (like our open-source tool, [git-xargs](https://github.com/gruntwork-io/git-xargs)), but using these can be cumbersome. That's why we recommend fewer git repos at the expense of empty versions, mitigated by tooling.
130-130: Simplify "ALL of the following" for conciseness.Line 130 can be made more concise by removing "of":
-Infrastructure modules should be scheduled for retirement when ALL of the following are true: +Infrastructure modules should be scheduled for retirement when all of the following are true:docs/2.0/way/principles/technical-foundations/represent-all-patterns-as-code.md (1)
34-34: Apply hyphen to "peer-reviewed" for consistency.Line 34 should use "peer-reviewed" as a hyphenated compound modifier:
-Representing patterns as code brings many benefits. To start, when anything is captured as code, it can be stored in version control. That means that every change is now tracked, attributed, and can be reverted if needed. Code can be peer reviewed, and automated tests can run to immediately validate the newly committed code. +Representing patterns as code brings many benefits. To start, when anything is captured as code, it can be stored in version control. That means that every change is now tracked, attributed, and can be reverted if needed. Code can be peer-reviewed, and automated tests can run to immediately validate the newly committed code.docs/2.0/way/platform/components/deploy/runbooks.md (3)
8-8: Improve markdown structure: convert emphasis to proper heading.Line 8 uses bold emphasis as a de facto heading, which violates markdown style guidelines. Convert it to a proper H3 heading:
-# Runbooks - -**How developers configure an infrastructure module instance** +# Runbooks + +### How developers configure an infrastructure module instance
67-67: Simplify redundant phrase "subject matter expertise."Line 67 uses "subject matter expertise," which is flagged as redundant. Simplify to just "subject expertise":
-**Documented.** The runbook must teach the user about this particular area of subject matter expertise, intermixing documentation and interactivity. +**Documented.** The runbook must teach the user about this particular area of subject expertise, intermixing documentation and interactivity.
150-150: Hyphenate "open-source" when used as compound adjective.Line 150 uses "open source" as a compound adjective and should be hyphenated:
-:::info -Gruntwork maintains an open source tool called [Gruntwork Runbooks](https://runbooks.gruntwork.io/) that is based on all the insights and philosophy that we capture here. Check it out! -::: +:::info +Gruntwork maintains an open-source tool called [Gruntwork Runbooks](https://runbooks.gruntwork.io/) that is based on all the insights and philosophy that we capture here. Check it out! +:::
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (47)
cspell.json(1 hunks)custom-dictionary.txt(0 hunks)docs/2.0/way/authorship.md(1 hunks)docs/2.0/way/intro/how-to-use-this.md(1 hunks)docs/2.0/way/intro/welcome.md(1 hunks)docs/2.0/way/intro/who-this-is-for.md(1 hunks)docs/2.0/way/platform/_category_.json(1 hunks)docs/2.0/way/platform/components/_category_.json(1 hunks)docs/2.0/way/platform/components/deploy/_category_.json(1 hunks)docs/2.0/way/platform/components/deploy/catalog.md(1 hunks)docs/2.0/way/platform/components/deploy/pipelines.md(1 hunks)docs/2.0/way/platform/components/deploy/runbooks.md(1 hunks)docs/2.0/way/platform/components/maintain/_category_.json(1 hunks)docs/2.0/way/platform/components/maintain/drift-detector.md(1 hunks)docs/2.0/way/platform/components/maintain/iac-updater.md(1 hunks)docs/2.0/way/platform/components/maintain/importer.md(1 hunks)docs/2.0/way/platform/components/maintain/scorecard.md(1 hunks)docs/2.0/way/platform/components/operate/_category_.json(1 hunks)docs/2.0/way/platform/components/operate/dashboards.md(1 hunks)docs/2.0/way/platform/components/operate/registry.md(1 hunks)docs/2.0/way/platform/components/operate/unit-browser.md(1 hunks)docs/2.0/way/platform/components/overview.md(1 hunks)docs/2.0/way/platform/interfaces/_category_.json(1 hunks)docs/2.0/way/platform/interfaces/overview.md(1 hunks)docs/2.0/way/platform/overview.md(1 hunks)docs/2.0/way/platform/patterns/_category_.json(1 hunks)docs/2.0/way/platform/patterns/good-patterns.md(1 hunks)docs/2.0/way/platform/patterns/infrastructure-modules/_category_.json(1 hunks)docs/2.0/way/platform/patterns/infrastructure-modules/authoring.md(1 hunks)docs/2.0/way/platform/patterns/infrastructure-modules/categories.md(1 hunks)docs/2.0/way/platform/patterns/infrastructure-modules/overview.md(1 hunks)docs/2.0/way/platform/patterns/overview.md(1 hunks)docs/2.0/way/platform/patterns/types.md(1 hunks)docs/2.0/way/platform/patterns/where-to-store-them.md(1 hunks)docs/2.0/way/principles/developer-experience/enable-developer-self-service.md(1 hunks)docs/2.0/way/principles/developer-experience/pre-built-patterns-are-your-leverage.md(1 hunks)docs/2.0/way/principles/developer-experience/shift-left.md(1 hunks)docs/2.0/way/principles/failure-modes.md(1 hunks)docs/2.0/way/principles/governance-maintainability/guardrails-over-gates.md(1 hunks)docs/2.0/way/principles/governance-maintainability/offer-golden-paths.md(1 hunks)docs/2.0/way/principles/technical-foundations/build-platform-components.md(1 hunks)docs/2.0/way/principles/technical-foundations/represent-all-patterns-as-code.md(1 hunks)docs/2.0/way/principles/technical-foundations/use-gitops.md(1 hunks)docs/2.0/way/why/governance.mdx(1 hunks)docs/2.0/way/why/maintainability.md(1 hunks)docs/2.0/way/why/overview.md(1 hunks)docs/2.0/way/why/velocity.md(1 hunks)
💤 Files with no reviewable changes (1)
- custom-dictionary.txt
✅ Files skipped from review due to trivial changes (10)
- docs/2.0/way/platform/components/operate/category.json
- docs/2.0/way/platform/patterns/infrastructure-modules/category.json
- docs/2.0/way/platform/components/deploy/category.json
- docs/2.0/way/platform/components/maintain/category.json
- docs/2.0/way/platform/components/maintain/scorecard.md
- docs/2.0/way/platform/patterns/category.json
- docs/2.0/way/platform/overview.md
- docs/2.0/way/platform/components/category.json
- docs/2.0/way/platform/interfaces/category.json
- docs/2.0/way/principles/technical-foundations/build-platform-components.md
🚧 Files skipped from review as they are similar to previous changes (5)
- docs/2.0/way/intro/how-to-use-this.md
- docs/2.0/way/authorship.md
- docs/2.0/way/principles/governance-maintainability/offer-golden-paths.md
- docs/2.0/way/principles/developer-experience/shift-left.md
- docs/2.0/way/principles/technical-foundations/use-gitops.md
🧰 Additional context used
📓 Path-based instructions (1)
docs/**/*.mdx
📄 CodeRabbit inference engine (.cursor/rules/gitlab-background.mdc)
Whenever presenting information that diverges between GitHub and GitLab, use the and components to distinguish the two sets of information UNLESS the distinction is just changing one word. For example, GitHub has pull requests and GitLab has merge requests, so we can just say '... pull/merge requests...' and not need full .
Files:
docs/2.0/way/why/governance.mdx
🧠 Learnings (1)
📚 Learning: 2025-07-17T18:43:27.029Z
Learnt from: ZachGoldberg
Repo: gruntwork-io/docs PR: 2663
File: docs/2.0/docs/pipelines/architecture/change-types.md:1-6
Timestamp: 2025-07-17T18:43:27.029Z
Learning: In the gruntwork-io/docs repository, document IDs should match the filename (without extension) rather than being namespaced. For example, a file named "change-types.md" should have `id: change-types` in the front matter.
Applied to files:
docs/2.0/way/intro/welcome.md
🪛 LanguageTool
docs/2.0/way/principles/developer-experience/enable-developer-self-service.md
[style] ~18-~18: To elevate your writing, try using a synonym here.
Context: ...lf-service is highly valuable, but also hard to get right.
(HARD_TO)
docs/2.0/way/platform/patterns/infrastructure-modules/categories.md
[style] ~10-~10: This phrase is redundant. Consider using “subject” to avoid wordiness.
Context: ...odules. Each category has one or more subject matter expertise topics (SME topics). Each S...
(SUBJECT_MATTER)
docs/2.0/way/platform/patterns/types.md
[style] ~61-~61: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ration, troubleshooting, and recovery. Runbooks can be especially well-suited to genera...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/2.0/way/platform/patterns/good-patterns.md
[grammar] ~159-~159: Use a hyphen to join words.
Context: ...runtwork subject matter expert, and peer reviewed by other Gruntwork subject matt...
(QB_NEW_EN_HYPHEN)
docs/2.0/way/intro/welcome.md
[grammar] ~39-~39: Use a hyphen to join words.
Context: ... Makers - We've created leading open source DevOps tooling like [OpenTofu](ht...
(QB_NEW_EN_HYPHEN)
docs/2.0/way/why/maintainability.md
[style] ~21-~21: Consider using a more concise synonym.
Context: ...the infrastructure world, debt takes on a variety of forms: - Drift - Your infrastructu...
(A_VARIETY_OF)
[style] ~26-~26: ‘many different ways’ might be wordy. Consider a shorter alternative.
Context: ...organization solves the same problem in many different ways We pay off infrastructure debt with _r...
(EN_WORDINESS_PREMIUM_MANY_DIFFERENT_WAYS)
docs/2.0/way/why/overview.md
[style] ~28-~28: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...s it satisfy our legal obligations? - Is it secure? Will it protect our custom...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~29-~29: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ill it protect our customers' data? - Is it reliable? Will this work as expect...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~40-~40: ‘many different ways’ might be wordy. Consider a shorter alternative.
Context: ...organization solves the same problem in many different ways Achieving maintainability is about ide...
(EN_WORDINESS_PREMIUM_MANY_DIFFERENT_WAYS)
[style] ~52-~52: This phrase is redundant. Consider writing “moment” or “time”.
Context: ...inability for your organization at this moment in time, and adjusting that balance as your nee...
(MOMENT_IN_TIME)
docs/2.0/way/principles/governance-maintainability/guardrails-over-gates.md
[uncategorized] ~14-~14: Do not mix variants of the same word (‘judgment’ and ‘judgement’) within a single text.
Context: ...ail, you are reducing that manual human judgment down to a narrowly scoped rule that sys...
(EN_WORD_COHERENCY)
docs/2.0/way/principles/technical-foundations/represent-all-patterns-as-code.md
[style] ~25-~25: To elevate your writing, try using a synonym here.
Context: ...id the original configuration, and it's hard to track or know about any updates to t...
(HARD_TO)
[grammar] ~34-~34: Use a hyphen to join words.
Context: ... be reverted if needed. Code can be peer reviewed, and automated tests can run to...
(QB_NEW_EN_HYPHEN)
[style] ~49-~49: ‘emergency situations’ might be wordy. Consider a shorter alternative.
Context: ... code does take more time. Sometimes in emergency situations, engineers might need to optimize for s...
(EN_WORDINESS_PREMIUM_EMERGENCY_SITUATIONS)
docs/2.0/way/principles/developer-experience/pre-built-patterns-are-your-leverage.md
[grammar] ~22-~22: Use a hyphen to join words.
Context: ...uthored inhouse, or "vendored" from open source or commercial pattern libraries (...
(QB_NEW_EN_HYPHEN)
docs/2.0/way/intro/who-this-is-for.md
[style] ~20-~20: This phrase is redundant. Consider writing “components” or “parts”.
Context: ...e collection of maturity levels for its component parts. In general, the component parts track...
(COMPONENT_PART)
[style] ~22-~22: This phrase is redundant. Consider writing “components” or “parts”.
Context: ...r its component parts. In general, the component parts track these maturity levels: - **Ad ho...
(COMPONENT_PART)
docs/2.0/way/platform/components/deploy/catalog.md
[grammar] ~58-~58: Use a hyphen to join words.
Context: ...e a git repository. :::info In our open source tool, Terragrunt, we expose a [te...
(QB_NEW_EN_HYPHEN)
docs/2.0/way/platform/components/deploy/runbooks.md
[style] ~19-~19: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...tructure module - Perform other actions needed to meet the pre-requisites (e.g. obtain a ...
(REP_NEED_TO_VB)
[style] ~67-~67: This phrase is redundant. Consider using “subject” to avoid wordiness.
Context: ... the user about this particular area of subject matter expertise, intermixing documentation an...
(SUBJECT_MATTER)
[uncategorized] ~150-~150: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...author. :::info Gruntwork maintains an open source tool called [Gruntwork Runbooks](https:...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
docs/2.0/way/platform/components/overview.md
[grammar] ~14-~14: Ensure spelling is correct
Context: ...omponents One of the core ideas of The Gruntowrk Way is that you build your developer pl...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~20-~20: This phrase can be considered informal. To elevate your writing, consider using a more professional alternative.
Context: ...0/way/platform/interfaces/overview) We talk about components individually because that is...
(TALK_ABOUT_DISCUSS)
[style] ~54-~54: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...nts. You can build some and buy others. You can also choose to optimize for "best o...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/2.0/way/platform/interfaces/overview.md
[style] ~16-~16: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...CLI The CLI works well when developers want to interact with your platform directly fr...
(REP_WANT_TO_VB)
docs/2.0/way/platform/patterns/infrastructure-modules/authoring.md
[grammar] ~32-~32: Use a hyphen to join words.
Context: ... control, low convenience) 2. Use open source infrastructure modules - You fi...
(QB_NEW_EN_HYPHEN)
[grammar] ~40-~40: Use a hyphen to join words.
Context: ...per module. For example, you use an open source AWS Lambda module, but write your...
(QB_NEW_EN_HYPHEN)
[grammar] ~40-~40: Use a hyphen to join words.
Context: ...cme AWS Lambda module that uses the open source AWS Lambda module. 3. Fork - ...
(QB_NEW_EN_HYPHEN)
[grammar] ~112-~112: Use a hyphen to join words.
Context: ...ge many git repos at once (like our open source tool, [git-xargs](https://github....
(QB_NEW_EN_HYPHEN)
[style] ~130-~130: Consider removing “of” to be more concise
Context: ...should be scheduled for retirement when ALL of the following are true: - **Better alterna...
(ALL_OF_THE)
[style] ~135-~135: Consider replacing ‘often’ with a more meaningful word.
Context: ... a module if it is simply not used very often. By reducing your surface area, you inc...
(VERY_RB_STYLE)
docs/2.0/way/platform/patterns/overview.md
[style] ~25-~25: This phrase is redundant. Consider using “subject” to avoid wordiness.
Context: ...**_ Any DevOps challenge that requires subject matter expertise can be captured as a pattern....
(SUBJECT_MATTER)
[style] ~25-~25: Consider removing “of” to be more concise
Context: ... be captured as a pattern. For example, all of the following are common DevOps problems th...
(ALL_OF_THE)
[style] ~25-~25: This phrase is redundant. Consider using “subject” to avoid wordiness.
Context: ...ps problems that require some degree of subject matter expertise to solve: - Building a stand...
(SUBJECT_MATTER)
[style] ~37-~37: This phrasing can be wordy, so consider using a more descriptive and concise alternative.
Context: ...t DevOps is "broad and shallow," and as you can see in the list above, patterns can indeed spa...
(AS_YOU_CAN_SEE)
[style] ~39-~39: This phrase can be considered informal. To elevate your writing, consider using a more professional alternative.
Context: ... indeed span a wide range of areas. We talk about patterns as a first-class concept becau...
(TALK_ABOUT_DISCUSS)
docs/2.0/way/platform/patterns/where-to-store-them.md
[style] ~13-~13: ‘with respect to’ might be wordy. Consider a shorter alternative.
Context: ...they often have limited functionality with respect to these infrastructure-as-code pattern ty...
(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
docs/2.0/way/principles/failure-modes.md
[grammar] ~63-~63: Use a hyphen to join words.
Context: ...s wherever possible. These could be open source modules, or commercial module cat...
(QB_NEW_EN_HYPHEN)
docs/2.0/way/why/governance.mdx
[style] ~11-~11: To elevate your writing, try using a synonym here.
Context: ...ely, the goal is to make non-compliance hard to do rather than easy to do. ## What ...
(HARD_TO)
[grammar] ~17-~17: Use a hyphen to join words.
Context: ...hemselves a few key questions: - Cost effectiveness - Can you afford the inf...
(QB_NEW_EN_HYPHEN)
[style] ~80-~80: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...ands. At the same time, governance has a very large surface area and you can easily overwhe...
(EN_WEAK_ADJECTIVE)
🪛 markdownlint-cli2 (0.18.1)
docs/2.0/way/platform/patterns/infrastructure-modules/categories.md
59-59: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/why/overview.md
10-10: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
docs/2.0/way/platform/components/deploy/catalog.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/platform/components/deploy/pipelines.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/platform/components/deploy/runbooks.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/platform/components/maintain/drift-detector.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/platform/components/maintain/iac-updater.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/platform/components/maintain/importer.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/platform/components/operate/dashboards.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/platform/components/operate/registry.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/2.0/way/platform/components/operate/unit-browser.md
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)
- GitHub Check: Cursor Bugbot
- GitHub Check: Validate generated content
- GitHub Check: Pull Request has non-contributor approval
- GitHub Check: Pull Request has non-contributor approval
- GitHub Check: validate_build
🔇 Additional comments (10)
docs/2.0/way/why/governance.mdx (1)
1-126: Content and structure look solid.The governance page is well-organized, with clear sections on what governance is, how to improve it, and how to measure it. The internal links are properly formatted and the progression from state to flow metrics is instructive. Nice work on this comprehensive reference.
docs/2.0/way/principles/governance-maintainability/guardrails-over-gates.md (1)
1-24: Excellent framing of an important principle.This page does a great job contrasting the trade-offs between manual approval processes and automated guardrails, and makes a compelling case for why guardrails are the way forward. The examples are concrete and the connection to the IaC pipeline is helpful.
docs/2.0/way/principles/failure-modes.md (1)
1-67: Great structure for communicating common pitfalls.The failure modes page effectively pairs each problem with concrete prevention strategies. The progression from adoption through technical debt to standardization to leverage is logical, and the cross-references to other principles reinforce the interconnected nature of the Way framework. This will be a valuable reference for platform teams.
docs/2.0/way/why/velocity.md (1)
1-125: Comprehensive and well-paced introduction to velocity.This page effectively defines velocity, breaks down its components, and provides both strategic guidance (pre-built patterns, self-service) and practical measurement approaches. The inclusion of DORA metrics and the excerpt on world-class software delivery adds credibility and helps teams understand the scale of possible improvements. The connection between velocity improvements and governance/maintainability (in the Next section) is a nice segue to the broader Way framework.
docs/2.0/way/platform/patterns/where-to-store-them.md (1)
1-14: Concise and practical.This short page effectively positions the Catalog as the storage mechanism for patterns and gives readers a quick mental model of implementation options. The progression from simplest (Git) to most feature-rich (Native IaC catalogs) is intuitive.
docs/2.0/way/platform/_category_.json (1)
1-6: Valid category metadata.The category is properly structured and positioned. The
way-top-level-itemclass aligns with CSS styling updates for top-level Way sidebar items.docs/2.0/way/platform/components/deploy/pipelines.md (1)
1-23: Clear and well-structured component documentation.The Pipelines page effectively explains what pipelines are, why they matter, and what capabilities they enable. The list of capabilities (automated deployment, policy enforcement, testing, rollback, audit trails) is comprehensive and well-organized.
docs/2.0/way/platform/components/deploy/catalog.md (1)
1-59: Comprehensive breakdown of catalog requirements and options.This page provides excellent clarity on what makes a good catalog by distinguishing between minimum requirements and effective catalogs. The progression from "no system of record" through various implementation options helps teams understand the trade-offs and plan their roadmap. The inclusion of the Terragrunt example is a nice concrete touchpoint.
cspell.json (2)
129-150: Verify regex patterns and configuration fields.The regex patterns for ignoring URLs and code blocks (lines 145–146) should be validated. Additionally, ensure that the
dictionariesandenableFiletypesfields are correctly configured for your use case.Please verify:
- The regex patterns
/https?:\/\/[^\s]+/gand/```[\s\S]*?```/gcorrectly match URLs and fenced code blocks as intended- The
dictionarieslist (TypeScript, Node, npm, Bash, Markdown) aligns with the project's needs- The
enableFiletypeslist includes all file types in the repository that need spell-checkingThe empty
ignoreWordsarray (line 129) appears intentional—confirm this is the desired behavior.
2-3: No compatibility issues found.cspell version 0.2 supports all configuration fields specified in this file, including the
wordsarray,ignoreWords,ignorePaths,ignoreRegExpList,allowCompoundWords, anddictionaries. The configuration structure is compatible.
| "words": [ | ||
| "Gruntwork", | ||
| "gruntwork", | ||
| "GitOps", | ||
| "Docusaurus", | ||
| "runbooks", | ||
| "terraform", | ||
| "terragrunt", | ||
| "Terragrunt", | ||
| "kubernetes", | ||
| "kubectl", | ||
| "autoscaling", | ||
| "monorepo", | ||
| "microservices", | ||
| "infra", | ||
| "DevOps", | ||
| "OpenTofu", | ||
| "opentofu", | ||
| "Tofu", | ||
| "prebuilt", | ||
| "repo", | ||
| "repos", | ||
| "serverless", | ||
| "cloudformation", | ||
| "elasticache", | ||
| "cicd", | ||
| "gitignore", | ||
| "cursorrules", | ||
| "npmignore", | ||
| "lockfile", | ||
| "lockfiles", | ||
| "docstrings", | ||
| "codebase", | ||
| "codebases", | ||
| "runbook", | ||
| "dockerfile", | ||
| "dockerfiles", | ||
| "orchestrator", | ||
| "orchestrators", | ||
| "customizable", | ||
| "composability", | ||
| "scalability", | ||
| "observability", | ||
| "linter", | ||
| "linters", | ||
| "linting", | ||
| "Yousif", | ||
| "Oreoluwa", | ||
| "Agunbiade", | ||
| "Yevgeniy", | ||
| "Brikman", | ||
| "Rahul", | ||
| "Vohra", | ||
| "Nana", | ||
| "Pulumi", | ||
| "pulumi", | ||
| "Rego", | ||
| "Sonatype", | ||
| "Pgvector", | ||
| "karpenter", | ||
| "Karpenter", | ||
| "MTTR", | ||
| "MTTP", | ||
| "inhouse", | ||
| "SOURCER", | ||
| "mydomain", | ||
| "terratest", | ||
| "Terratest", | ||
| "terratests", | ||
| "tailscale", | ||
| "sdlc", | ||
| "acmecorp", | ||
| "envcommon", | ||
| "tada", | ||
| "codeowners", | ||
| "jsonencode", | ||
| "chdir", | ||
| "rulesets", | ||
| "controltower", | ||
| "awscli", | ||
| "passwordless", | ||
| "coolapp", | ||
| "acmeco", | ||
| "grunty", | ||
| "yamldecode", | ||
| "mgmt", | ||
| "tfstate", | ||
| "baselining", | ||
| "baselined", | ||
| "clickops", | ||
| "terrascan", | ||
| "steampipe", | ||
| "infracost", | ||
| "kubergrunt", | ||
| "terraformrc", | ||
| "tfvars", | ||
| "fargate", | ||
| "keypair", | ||
| "mimecast", | ||
| "slugified", | ||
| "dlist", | ||
| "DEPENDENCYID", | ||
| "subfolders", | ||
| "terrapatch", | ||
| "Terrapatch", | ||
| "KodeKloud", | ||
| "preconfigured", | ||
| "projectprefix", | ||
| "GOVCLOUD", | ||
| "rollouts", | ||
| "myvars", | ||
| "myfile", | ||
| "minamijoyo", | ||
| "tfupdate", | ||
| "hcledit", | ||
| "infrachanges", | ||
| "Entra", | ||
| "GLMU", | ||
| "myprodsa", | ||
| "azuread", | ||
| "mysa", | ||
| "deinterlaced", | ||
| "rolename", | ||
| "ACCOUNTNAME" | ||
| ], |
There was a problem hiding this comment.
🧩 Analysis chain
Verify word list migration from deleted custom-dictionary.txt.
The configuration consolidates spell-checker terms into an inline words array (127 terms). Since custom-dictionary.txt was deleted in this PR, we need to ensure all terms were successfully migrated.
Please verify that:
- All domain-specific terms from the deleted
custom-dictionary.txthave been migrated to this array - No terms were accidentally omitted during the transition
- No duplicate entries exist in the array
You can run this script to check for duplicates within the current word list:
🏁 Script executed:
#!/bin/bash
# Description: Check for duplicate entries in the words array of cspell.json
# Expected result: No duplicates should be found
# Extract the words array and sort to find duplicates
jq '.words | sort | .[] as $word | {word: $word}' cspell.json | \
jq -s 'group_by(.word) | map(select(length > 1)) | if length > 0 then . else "No duplicates found" end'Length of output: 21
I'll verify the remaining aspects of the migration by checking the git history and confirming the file deletion.
Let me try a different approach with the repository:
---
🏁 Script executed:
```shell
#!/bin/bash
# Check git history for custom-dictionary.txt deletion and show what was removed
git log --diff-filter=D --summary | grep -A 5 "custom-dictionary.txt" || echo "No deletion found in recent history"
echo "---"
# Show the git diff for the PR if available to see file removals
git show --name-status | head -30 || echo "No git show available"
echo "---"
# Look for any remaining spell-check or dictionary configuration files
fd -e txt -e json | grep -i -E "(dict|spell|custom)" || echo "No matching config files found"
Length of output: 836
🏁 Script executed:
#!/bin/bash
# Check if custom-dictionary.txt exists in the current state
if [ -f "custom-dictionary.txt" ]; then
echo "custom-dictionary.txt found. Contents:"
cat custom-dictionary.txt
else
echo "custom-dictionary.txt does not exist in current state"
fi
echo "---"
# List all files in root to see what spell-check configs exist
echo "Files in root directory:"
ls -la | grep -E "\.(json|txt)$" || echo "No matching files"
echo "---"
# Check git log for the deletion
if git log --oneline --all 2>/dev/null | head -5; then
echo "Git available. Checking for file deletion..."
git log --follow -- custom-dictionary.txt 2>/dev/null | head -20 || echo "No git history for custom-dictionary.txt"
fiLength of output: 1583
Now let me retrieve the original contents of the deleted file to verify the migration was complete:
🏁 Script executed:
#!/bin/bash
# Retrieve the deleted custom-dictionary.txt from git history
echo "=== Original custom-dictionary.txt contents ==="
git show HEAD~1:custom-dictionary.txt 2>/dev/null || git show c48840aa:custom-dictionary.txt 2>/dev/null || git show 48ae2b94^:custom-dictionary.txt 2>/dev/null || echo "Could not retrieve file"
echo ""
echo "=== Current cspell.json words array (first 10 for reference) ==="
jq '.words[:10]' cspell.json
echo ""
echo "=== Total words in current array ==="
jq '.words | length' cspell.jsonLength of output: 972
Let me verify these potential omissions:
🏁 Script executed:
#!/bin/bash
# Check if the missing terms exist in current cspell.json
echo "=== Checking for 'gruntwork-io' in current cspell.json ==="
jq '.words[] | select(. == "gruntwork-io")' cspell.json || echo "NOT FOUND"
echo ""
echo "=== Checking for 'self-hosting' in current cspell.json ==="
jq '.words[] | select(. == "self-hosting")' cspell.json || echo "NOT FOUND"
echo ""
echo "=== Listing all current words for reference ==="
jq '.words | sort' cspell.jsonLength of output: 1925
Add missing terms from deleted custom-dictionary.txt
Migration verification found two domain-specific terms that were not carried over to the words array:
gruntwork-ioself-hosting
These should be added to the words array in cspell.json to complete the migration. No duplicates were found, and all other 70 original terms were successfully migrated.
🤖 Prompt for AI Agents
In cspell.json around lines 4 to 128, the review notes that two domain-specific
terms from the deleted custom-dictionary.txt are missing: "gruntwork-io" and
"self-hosting"; update the "words" array by adding these two entries (exact
spelling and hyphenation) ensuring they are not duplicated and follow the same
formatting as the existing entries.
| # Drift Detector | ||
|
|
||
| **Detect drift between code and cloud** |
There was a problem hiding this comment.
Convert bolded tagline to proper heading for markdown compliance.
Line 8 uses bold emphasis instead of a heading structure. While this creates a visual tagline effect, it violates the markdown linting rule (MD036) that flags emphasis used as headings.
Apply this diff:
# Drift Detector
- **Detect drift between code and cloud**
+ ## Detect drift between code and cloud📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Drift Detector | |
| **Detect drift between code and cloud** | |
| # Drift Detector | |
| ## Detect drift between code and cloud |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In docs/2.0/way/platform/components/maintain/drift-detector.md around lines 6 to
8, the second line currently uses bold emphasis as a tagline ("**Detect drift
between code and cloud**") which violates MD036; replace that bolded line with a
proper Markdown heading (e.g., "### Detect drift between code and cloud" or an
appropriate H2/H3 level consistent with surrounding headings) so it becomes a
real heading instead of emphasized text, maintaining the same wording and
adjusting heading level to match the document's hierarchy.
| # IaC Updater | ||
|
|
||
| **Update out-of-date IaC or tooling versions** |
There was a problem hiding this comment.
Convert bold emphasis to a proper Markdown heading.
Line 8 violates the MD036 linting rule by using bold emphasis instead of a semantic heading. Convert to:
# IaC Updater
-**Update out-of-date IaC or tooling versions**
+## Update out-of-date IaC or tooling versions📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # IaC Updater | |
| **Update out-of-date IaC or tooling versions** | |
| # IaC Updater | |
| ## Update out-of-date IaC or tooling versions |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In docs/2.0/way/platform/components/maintain/iac-updater.md around lines 6 to 8,
the second line uses bold emphasis instead of a semantic heading (MD036).
Replace the bold text "**Update out-of-date IaC or tooling versions**" with an
appropriate Markdown heading (for example "## Update out-of-date IaC or tooling
versions"), preserving surrounding content and ensuring a blank line before and
after the heading so the file conforms to markdownlint rules.
| # Dashboards and Data Visualization | ||
|
|
||
| **Translate data points into insights** |
There was a problem hiding this comment.
Convert bolded tagline to proper heading for markdown compliance.
Line 8 uses bold emphasis instead of a heading structure. While this creates a visual tagline effect, it violates the markdown linting rule (MD036) that flags emphasis used as headings.
Apply this diff:
# Dashboards and Data Visualization
- **Translate data points into insights**
+ ## Translate data points into insights📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Dashboards and Data Visualization | |
| **Translate data points into insights** | |
| # Dashboards and Data Visualization | |
| ## Translate data points into insights |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In docs/2.0/way/platform/components/operate/dashboards.md around lines 6 to 8,
replace the bolded tagline line ("**Translate data points into insights**") with
a proper Markdown heading (e.g., "### Translate data points into insights" or
another appropriate heading level consistent with the surrounding document),
ensuring it uses a heading marker rather than emphasis so it passes MD036
linting; keep the same text and update only the markup.
| # Registry | ||
|
|
||
| **Where you see and manage what the business is running** |
There was a problem hiding this comment.
Convert bold emphasis to a proper Markdown heading.
Line 8 violates the MD036 linting rule (same issue as other component docs). Convert to:
# Registry
-**Where you see and manage what the business is running**
+## Where you see and manage what the business is running📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Registry | |
| **Where you see and manage what the business is running** | |
| # Registry | |
| ## Where you see and manage what the business is running |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In docs/2.0/way/platform/components/operate/registry.md around lines 6 to 8, the
second line uses bold text for a section title ("**Where you see and manage what
the business is running**") which violates MD036; replace that bold emphasis
with a proper Markdown heading (e.g., change the bolded line to start with an
appropriate number of '#' characters matching the document structure, and remove
the surrounding **), ensuring heading level matches surrounding docs and update
any adjacent spacing so the file passes MD036.
| # Unit Browser | ||
|
|
||
| **How to browse what infrastructure is deployed** |
There was a problem hiding this comment.
Convert bolded tagline to proper heading for markdown compliance.
Line 8 uses bold emphasis instead of a heading structure. While this creates a visual tagline effect, it violates the markdown linting rule (MD036) that flags emphasis used as headings.
Apply this diff:
# Unit Browser
- **How to browse what infrastructure is deployed**
+ ## How to browse what infrastructure is deployed📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Unit Browser | |
| **How to browse what infrastructure is deployed** | |
| # Unit Browser | |
| ## How to browse what infrastructure is deployed |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
8-8: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In docs/2.0/way/platform/components/operate/unit-browser.md around lines 6 to 8,
the descriptive tagline currently formatted as bold emphasis should be converted
into a proper markdown heading to satisfy MD036; replace the bolded line with an
appropriate heading (e.g., "## How to browse what infrastructure is deployed" or
"###" if a lower level is required by surrounding headings) so it uses a heading
token instead of emphasis.
| - Queues & streams (Amazon Kinesis, Amazon SQS) | ||
| - Time-series databases (Tiger Data, InfluxDB) | ||
|
|
||
| _Examples: AWS RDS databases, Amazon S3 buckets, AWS DynamoDB tables, Amazon Kinesis streams_ |
There was a problem hiding this comment.
Convert italicized label to plain text or proper heading.
Line 59 uses italics for "Examples:" which violates markdown formatting conventions. Either remove the emphasis or convert to a proper heading structure.
Apply this diff:
- _Examples: AWS RDS databases, Amazon S3 buckets, AWS DynamoDB tables, Amazon Kinesis streams_
+ Examples: AWS RDS databases, Amazon S3 buckets, AWS DynamoDB tables, Amazon Kinesis streams📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| _Examples: AWS RDS databases, Amazon S3 buckets, AWS DynamoDB tables, Amazon Kinesis streams_ | |
| Examples: AWS RDS databases, Amazon S3 buckets, AWS DynamoDB tables, Amazon Kinesis streams |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
59-59: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
docs/2.0/way/platform/patterns/infrastructure-modules/categories.md around line
59: the label "_Examples:_" is italicized; remove the emphasis and replace it
with either plain text "Examples:" or a proper markdown heading like "###
Examples" and ensure the rest of the example list remains unchanged and
correctly formatted as sentence or list items.
|
|
||
| # Enable developer self-service | ||
|
|
||
| The ideal velocity for application developers is that they get the infrastructure they need, when they need it, without human gatekeepers. This known as **developer self-service.** |
There was a problem hiding this comment.
Fix grammar: missing "is" in sentence.
Line 8 reads "This known as developer self-service." but should be:
-The ideal velocity for application developers is that they get the infrastructure they need, when they need it, without human gatekeepers. This known as **developer self-service.**
+The ideal velocity for application developers is that they get the infrastructure they need, when they need it, without human gatekeepers. This is known as **developer self-service.**📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| The ideal velocity for application developers is that they get the infrastructure they need, when they need it, without human gatekeepers. This known as **developer self-service.** | |
| The ideal velocity for application developers is that they get the infrastructure they need, when they need it, without human gatekeepers. This is known as **developer self-service.** |
🤖 Prompt for AI Agents
In docs/2.0/way/principles/developer-experience/enable-developer-self-service.md
around line 8, the sentence "This known as **developer self-service.**" is
missing the verb "is"; update the sentence to "This is known as **developer
self-service.**" to correct the grammar.
|
|
||
| When companies write their own software with more than a few developers, they need to find a way to balance **three fundamental concerns**. | ||
|
|
||
| ### 1. Velocity |
There was a problem hiding this comment.
Fix heading level hierarchy violation.
Line 10 uses an H3 heading (###) but should be H2 (##) based on the document structure. The H1 is on line 6, so the next level should be H2.
Apply this diff:
- ### 1. Velocity
+ ## 1. VelocityThen apply the same fix to lines 20 and 31:
- ### 2. Governance
+ ## 2. Governance- ### 3. Maintainability
+ ## 3. Maintainability📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### 1. Velocity | |
| ## 1. Velocity |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
10-10: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
In docs/2.0/way/why/overview.md around line 10 (and also lines 20 and 31), the
headings use H3 (###) but should be H2 (##) to maintain proper hierarchy under
the H1 on line 6; update those three heading lines from "### ..." to "## ..." so
the document structure is consistent.
Hit my time limit for getting it working.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/2.0/way/platform/components/overview.md (2)
20-20: Consider using "discuss" instead of the more informal "talk about."Line 20 uses "We talk about components individually," which reads slightly informal. Replacing "talk about" with "discuss" would elevate the writing tone while maintaining clarity.
Apply this diff:
-We talk about components individually because that is the most helpful way to think about them. But in practice, your end users may simply see a "developer platform" and the lines between specific components may be blurry. +We discuss components individually because that is the most helpful way to think about them. But in practice, your end users may simply see a "developer platform" and the lines between specific components may be blurry.
52-55: Reduce repetition of "You can" at the start of successive sentences.Lines 54–55 have three consecutive sentences starting with "You can," which creates a rhythmically repetitive pattern. Consider varying the sentence structure to improve flow.
Apply this diff:
-You can choose to build or buy most of these components. You can build some and buy others. You can also choose to optimize for "best of breed" (the best individual component) or "best of suite" (the best combination of components), or mix and match build and buy to suit your needs. +You can choose to build or buy most of these components. Build some and buy others—or optimize for "best of breed" (the best individual component) versus "best of suite" (the best combination of components), mixing and matching build and buy to suit your needs.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/2.0/way/platform/components/overview.md(1 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: ZachGoldberg
Repo: gruntwork-io/docs PR: 2663
File: docs/2.0/docs/pipelines/architecture/change-types.md:1-6
Timestamp: 2025-07-17T18:43:27.029Z
Learning: In the gruntwork-io/docs repository, document IDs should match the filename (without extension) rather than being namespaced. For example, a file named "change-types.md" should have `id: change-types` in the front matter.
📚 Learning: 2025-07-17T18:43:27.029Z
Learnt from: ZachGoldberg
Repo: gruntwork-io/docs PR: 2663
File: docs/2.0/docs/pipelines/architecture/change-types.md:1-6
Timestamp: 2025-07-17T18:43:27.029Z
Learning: In the gruntwork-io/docs repository, document IDs should match the filename (without extension) rather than being namespaced. For example, a file named "change-types.md" should have `id: change-types` in the front matter.
Applied to files:
docs/2.0/way/platform/components/overview.md
🪛 LanguageTool
docs/2.0/way/platform/components/overview.md
[style] ~20-~20: This phrase can be considered informal. To elevate your writing, consider using a more professional alternative.
Context: ...0/way/platform/interfaces/overview) We talk about components individually because that is...
(TALK_ABOUT_DISCUSS)
[style] ~54-~54: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...nts. You can build some and buy others. You can also choose to optimize for "best o...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)
- GitHub Check: Cursor Bugbot
- GitHub Check: Pull Request has non-contributor approval
- GitHub Check: Pull Request has non-contributor approval
- GitHub Check: validate_build
- GitHub Check: Validate generated content
🔇 Additional comments (1)
docs/2.0/way/platform/components/overview.md (1)
14-14: Verify the spelling correction from the previous review.A previous review flagged a critical spelling error on line 14 ("Gruntowrk" → "Gruntwork"). The current version correctly shows "The Gruntwork Way." Please confirm this was intentionally fixed in your latest changes.
| --- | ||
| sidebar_position: 1 | ||
| title: Overview | ||
| --- |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add id field to front matter matching the filename.
The front matter is missing an id field. Per the repository's convention, document IDs should match the filename (without extension). This file should have id: overview.
Apply this diff:
---
sidebar_position: 1
title: Overview
+id: overview
---Based on learnings from previous reviews in this repository.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --- | |
| sidebar_position: 1 | |
| title: Overview | |
| --- | |
| --- | |
| sidebar_position: 1 | |
| title: Overview | |
| id: overview | |
| --- |
🤖 Prompt for AI Agents
In docs/2.0/way/platform/components/overview.md around lines 1 to 4, the front
matter is missing an id field; add a line id: overview to the YAML front matter
so the document ID matches the filename (overview.md) per repository convention,
ensuring it appears alongside the existing sidebar_position and title entries.
Launch The Gruntwork Way on the Gruntwork docs site. This officially replaces https://github.com/gruntwork-io/way, and all future Gruntwork Way updates should happen in this repo.
Note
Introduces a comprehensive “Gruntwork Way” documentation section with navigation integration, plus spellcheck reconfig and minor styling/tooling updates.
docs/2.0/waywith category configs.cspell.json(words, ignore paths/regex, filetypes); removescustom-dictionary.txt.husky; updates lockfile.Written by Cursor Bugbot for commit 9a47904. This will update automatically on new commits. Configure here.
Summary by CodeRabbit
Documentation
Chores
✏️ Tip: You can customize this high-level summary in your review settings.