Repository navigation
[draft] Solutions page - #4760
Draft
Chef-Pradyumn wants to merge 34 commits into
Draft
Chef-Pradyumn wants to merge 34 commits into
Chef-Pradyumn wants to merge 34 commits into
Conversation
- New content/solutions/_index.md: task/outcome-oriented Solutions homepage (card grid), with Compliance as the first fully-built solution and the remaining 7 areas from the Chef Docs Strategy & Information Architecture proposal marked 'Coming soon'. - New content/solutions/compliance/_index.md: Compliance solution overview page linking Chef InSpec, Chef Automate, Chef Infra Client, and Chef 360 into a single author -> scan -> visualize -> remediate -> orchestrate workflow, plus a benchmark coverage summary. - New content/solutions/compliance/<category>/_index.md (9 pages): category landing pages styled after /inspec/resource_packs/, each listing current audit/remediation coverage for that category, sourced from the Chef Compliance - Current Support Coverage catalog (Operating Systems, Desktop / Client, Databases, Cloud, Containers / Kubernetes, Web Servers, Applications / Middleware, Virtualization, Network / Infrastructure). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
…-span benchmark names Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
…r Chef Compliance Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
…view pages; enable sidebar on Solutions Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
✅ Deploy Preview for chef-web-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
…idebar Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
Signed-off-by: Chef-Pradyumn <prabhu@progress.com>
Signed-off-by: Chef-Pradyumn <prabhu@progress.com>
Restructures the Compliance solution docs from a benchmark support matrix into a customer-outcome narrative, addressing review feedback that the content listed benchmarks without explaining what audit and remediation actually do or which real problems they solve. Overview page (content/solutions/compliance/_index.md): - Leads with the compliance problems Chef helps solve, not the catalog. - New reader journey: challenges -> how it works -> audit -> remediation -> scenarios -> coverage -> get started. - Adds a full "Compliance audit" section covering what is assessed, how a benchmark becomes runnable InSpec controls, the three ways to run an assessment, what results contain, how findings become a gap list, and how reports and waivers support evidence. - Adds a "Compliance remediation" section of equal depth covering what remediation content is, how it relates to benchmarks and controls, how it standardizes corrective action, how it pairs with audit, and what to check before using it. - Keeps audit and remediation distinct, and states explicitly that an audit version does not imply a matching remediation version. - Adds six real-world scenarios in problem -> approach -> outcome form. - Moves the coverage summary after the solution story and links out to the category pages. Category pages: - Regenerated from the validated internal catalog so the tables are derived from evidence rather than hand-maintained. - Each page now links back to the audit, remediation, and coverage-table explanations on the overview. - Drops the internal "OTHER" canonicalization prefix from five benchmark names. "OTHER" records the absence of a framework token in the source filename; it is a pipeline artifact, not a product fact. Affected pages note that no framework is shown rather than inferring one. - Excludes two internal/preview rows that are not customer-facing. Those records are unchanged in the internal catalog. Published coverage is now stated as 132 benchmarks (60 audit and remediation, 59 audit only, 13 remediation only) across 191 audit versions and 101 remediation versions. The previous 134 figure counted the two excluded internal rows, and contradicted the category index on the same page, which already summed to 132. All benchmark versions remain visible; no version set is reduced to a latest version. Every capability statement is grounded in existing Chef documentation. No new product capabilities, metrics, customer claims, or workflows are introduced. In particular, the Compliance Phase is described as audit-only, which is what its documentation supports. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Kuxhul <kushalj@progress.com>
- Replace RHEL mention in marketing copy with Ubuntu Linux - Add missing hyperlinks across the Compliance overview - Link to Chef InSpec install docs from "Write your own controls" - Simplify tautological/double-negative sentences; deduplicate repeated audit/remediation explanation - Add Chef Automate mention to "Evidence and reporting" - Replace all "estate" references with "fleet" for consistency - Reword all "rather than" phrasing for plainer language - Remove Inferred Current (dagger-marked) benchmark entries and their explanatory paragraph; recompute coverage totals and per-category counts across all affected pages - Remove the "no framework prefix" explanatory note (no longer broadly applicable) - Fix sidebar menu order to match the "Browse by category" table - Remove duplicate Chef Premium Content entitlement sentence - Introduce "The Chef Way" branding across headings and body copy Signed-off-by: Chef-Pradyumn <264104377+Chef-Pradyumn@users.noreply.github.com>
clintoncwolfe
self-requested a review
October 8, 2026 13:16
clintoncwolfe
previously approved these changes
Oct 8, 2026
clintoncwolfe
left a comment
clintoncwolfe
left a comment
Contributor
There was a problem hiding this comment.
I like this - as a partial take, need more product line obviously. I;d like the Docs teams input as well; it's a product-oriented direction, obviously with some marketing content.
Adds a shared capability page explaining how to build custom compliance checks with Chef InSpec, plus contextual resource-pack sections on the four domain pages where a pack is genuinely relevant: Cloud, Containers / Kubernetes, Databases, and Applications / Middleware. The change is strictly additive over the approved baseline (da44770): 228 insertions and no deletions. The nine domain pages keep their URLs, front matter, benchmark tables, published figures, and sidebar order unchanged, including the removal of Inferred Current entries and the recomputed coverage totals. The domain page changes are made through the local catalog generator, which was reconciled to reproduce the approved pages byte-for-byte so regeneration can't restore the superseded tables. The new page states explicitly that a resource pack is not a benchmark and that pack availability does not indicate benchmark coverage. No sentence on a domain page contradicts the benchmark table above it. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Kushal J <kushalj@progress.com>
…nd installation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
Leadership feedback on PR chef#4760 was that the Compliance solution pages read as marketing rather than as solutions, and don't explain how to do anything. This addresses that without changing the approved benchmark catalog. Add a task-oriented walkthrough, "Audit SSH configuration across a Linux fleet", covering profile creation, control authoring, validation, execution, reading results and exit codes, fix-and-reassess, and waiving an accepted exception. Commands and CLI output were captured from real runs rather than written from memory. Remote SSH, cloud and Kubernetes commands come from the official CLI reference and are shown without fabricated output. Rework the custom checks page from an inventory into practical guidance, documenting the three resource pack distribution patterns with a worked example for each. Rewrite the six compliance scenarios so each ends in concrete linked steps instead of an aspirational outcome, and point two of them at specific steps of the walkthrough. Note plainly where no dedicated guide exists yet. Replace a promotional paragraph in "Getting Chef Compliance content" with actionable guidance, preserving its intent. The nine domain pages, benchmark tables, published figures, domain taxonomy, URLs and navigation weights are unchanged. Catalog regeneration produces no diff. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The cspell check failed on the Compliance overview. "walkthrough" is only present in @cspell/dict-software-terms, and the version bundled with cspell-action v2.1.1 doesn't include it, so CI flagged five occurrences that a locally installed newer dictionary accepted. Use "guide" instead, which is in the base en_US dictionary and so doesn't depend on the software-terms dictionary version. Link targets and anchors are unchanged. Signed-off-by: Kushal J <kushalj@progress.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Hands-on guide using the AWS resource pack: install/verify Chef InSpec, set up AWS credentials, write controls against S3, IAM, and security group resources, run the assessment, read results, fix and reassess, waive an accepted exception, and schedule recurring AWS scan jobs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
- Collapse the five 'Compliance challenges' subsections into one bulleted list instead of a prose essay. - Shorten the audit mechanics subsections (benchmark-to-profile, assessment results, evidence/reporting) that duplicated detail already documented at the Compliance Phase, scan jobs, and compliance reporting pages; link out instead of re-explaining. - Link the SSH baseline guide from where profiles are introduced. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
Replace the opening pitch-style intro and 'Compliance challenges Chef helps solve' agitate section with a concise intro, a direct problem statement, and a 'What this solution implements' section that routes straight to the SSH baseline and AWS foundations guides plus the scenarios list. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
Remove 'The Chef Way of Compliance' 6-step loop, now redundant with the problem statement and 'What this solution implements' section at the top of the page. Replace the 3-bullet 'Chef Way of compliance remediation' benefit pitch with one factual paragraph covering the same facts (consistent application, cookbook workflow, idempotent convergence). Drop a trailing sentence that just re-sold the numbered steps above it. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
Replace generic/awkward headings with ones that name the actual content: 'The problem' -> 'Why compliance drifts between audits', 'How a benchmark becomes something you can run' -> 'From benchmark to runnable profile', 'What remediation content is' -> 'Remediation content', 'How remediation content behaves' -> 'How remediation content runs', 'How audit and remediation work together' -> 'The audit, remediate, reassess cycle'. Update the matching internal anchor link. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
Merge or cut subsections whose content is already documented in detail elsewhere: 'From benchmark to runnable profile' (duplicates /inspec/profiles/), 'What an assessment gives you' and 'Evidence and reporting' (both duplicate /automate/reports/, merged into one 'Results and evidence' section), 'Remediation content' and 'How remediation content runs' (duplicate /client/.../cookbooks/ and general Chef Infra Client convergence docs, folded into the section intro), and 'The audit, remediate, reassess cycle' (duplicated the cycle already stated in 'What this solution implements'). Keep subsections that add information not found elsewhere: 'What gets assessed', 'How you run an assessment' (comparison table), 'How remediation relates to benchmarks and controls' (explains the audit/remediation version independence), and 'Before you use remediation content' (checklist). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
Fix the IAM control, which used three identifiers the AWS resource pack doesn't document: where(attached:) instead of only_attached, entry_names instead of policy_names, and an allow_actions property that doesn't exist on aws_iam_policy. Use have_statement, which the pack documents for this check, and note that it matches literal values without expanding wildcards. Add the vendoring step. inspec check and inspec exec both fail on an unfetched dependency, so the guide couldn't be followed end to end. Correct the generator output and inspec.yml guidance, which omitted inputs.yml and showed supports as platform-name rather than platform, and keep depends and supports in the edited inspec.yml so copying the example doesn't break the profile. Replace the inspec detect claim that a failure indicates a credentials problem. On InSpec 5.24.7 the command returns platform details with no credentials set, so it confirms the transport loaded and nothing more. Fold in the material from the S3 baseline draft: per-resource IAM permissions, exit codes, the Automate AWS API node manager path, the be_public object-ACL limitation, and a note recording which output was executed and which is illustrative. Add an extension section covering S3 default encryption and secure transport on the same profile. Remove the unresolved screenshot placeholder from the reporting note. Link the guide from the Compliance overview as a cloud scenario and from the Cloud domain page through the page generator. Signed-off-by: Kushal J <kushalj@progress.com>
The nine benchmark coverage pages describe what a licensed user receives, not how to solve a problem, so they didn't belong under Solutions. Move them to a top-level /premium_content/ section alongside the other product sections, and give the section a landing page that explains what Premium Content is, how audit and remediation content differ, and how to confirm entitlement. Keep the existing URLs working. Each moved page carries an alias for its old /solutions/compliance/ path, which the site's Netlify _redirects output picks up automatically. Move the coverage summary off the Compliance overview so the published figures have a single source. The overview keeps its heading and in-page anchors and now points to the coverage tables instead of restating them. Repoint the Chef Premium Content link in the Enterprise Edition page, which previously landed on a redirect stub for generic InSpec profile documentation. Published figures are unchanged: 127 benchmarks, 53 audit and remediation, 66 audit only, 8 remediation only, 191 audit versions, 84 remediation versions. Signed-off-by: Kushal J <kushalj@progress.com>
Rename 'InSpec GCP Resource Pack' to 'CIS Google Cloud Platform Foundations' in the cloud coverage table -- it's a resource pack is not a benchmark, but this release notes confirm a real CIS GCP Foundations benchmark exists, and the row was simply mislabeled. Move it into alphabetical order with the other cloud rows. Remove the 4-line 'audit and remediation coverage are tracked independently' explanation duplicated verbatim across all 9 category pages, since it's already stated once on the Premium Content index under 'Benchmark coverage'. Replace each page's two-paragraph intro with one sentence plus a link back to that section. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
Remove the page-less 'premium_content/benchmark_coverage' anchor node from menu.toml and reparent the 9 category pages directly under 'premium_content', matching the single-level nesting used by other working sections (e.g. Effortless). The intermediate anchor-only node had no backing content page, which prevented the sidebar from expanding to show the category children, making the left pane look like Premium Content had no sub-navigation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Pradyumn Prabhu <pradyumn.prabhu@progress.com>
Add repository assessment and organization-wide governance guides with resource examples, evidence handling, waivers, and recurring execution. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Jayamathans12 <jayams@progress.com>
Rename the five Compliance solution pages so each one carries the product framing agreed in the review, and drop the "Guide:" prefix from every sidebar entry. Page titles now read "The Chef way of <area> compliance". Sidebar labels stay short --- "AWS compliance", "SSH compliance", "GitHub repository compliance", "GitHub organization compliance", "Custom compliance checks" --- so the branded form appears in the page title, the browser title, and the breadcrumb without repeating a six-word prefix five times in the left pane. Add a "The Chef way" section to the Compliance overview that states the model once --- a control states the requirement, a profile groups the controls, a run produces a result --- and routes readers to the page closest to the systems they own. Renaming the pages would have cost the keywords the old titles carried, so each page now sets a `description` in front matter. The theme's head_summary partial prefers `.Params.description` over the generated summary, so the meta description keeps "audit an AWS account", "SSH configuration across a Linux fleet", and the rest. All slugs, URLs, weights, menu identifiers, and the nine /premium_content/ redirects are unchanged. Link text across the Compliance and Premium Content pages is updated to match the new titles. Port three generator drifts so docs/generate_compliance_pages.py reproduces the committed category pages byte for byte instead of reverting them on the next run: the deduplicated preamble, the flattened `premium_content` menu parent, and the GCP row rename. The rename is applied through a DISPLAY_OVERRIDES map in the publication layer rather than by editing the approved catalog, and rows are now sorted by display name so the renamed row lands in alphabetical position. Published figures are unchanged: 127 benchmarks, 53/66/8, 191 audit and 84 remediation versions. Add CODEOWNERS, ruleset, and rulesets to cspell.yaml. These are GitHub product terms used by the two GitHub pages and aren't in the shared Chef dictionaries. Validation: Vale, markdownlint, and cspell report zero issues across the 16 changed pages; Hugo builds 3732 pages cleanly; 306 internal links and anchors resolve; the generator is idempotent. Signed-off-by: Kushal J <kushalj@progress.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Clicking "Chef Compliance" in the sidebar did nothing. The entry was declared in menu.toml without a `url`, so it rendered as `<a href="">`. The only way into the overview was the "Overview" child beneath it, which pointed at the same page the parent should have opened. Declare the entry in content/solutions/compliance/_index.md instead, so the menu entry is the overview page. The link resolves to /solutions/compliance/ and the duplicate "Overview" row is gone. That alone would collapse the section as the reader arrives on it. The sidebar marks a section expanded with HasMenuCurrent, which is true only when one of its *children* is the current page; the "Overview" child was what kept it open. Override range_menu.html in the project layouts to also check IsMenuCurrent, so a section stays expanded when the parent entry is itself the current page. The override is a copy of the theme partial with that one condition changed, at all four nesting levels. It's inert for entries declared in menu.toml with a `url`, because Hugo associates no page with those, so it only affects sections that declare their parent on a page. Comparing a full build before and after: no URL added or removed, the Netlify redirects are byte-identical, and the only markup that changes is the compliance parent's href and the removed "Overview" row. Verified in a throwaway build that the parent URL alone, the partial override alone, and the front-matter entry on the stock partial each leave the section collapsed on the overview page. Both halves are required. Signed-off-by: Kushal J <kushalj@progress.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This reverts commit a685827. The change doesn't work in a browser. The sidebar is a Foundation accordion menu, and AccordionMenu binds this to every parent link that has a submenu: $(this).children('a').off('click.zf.accordionMenu') .on('click.zf.accordionMenu', function(e) { e.preventDefault(); _this.toggle($submenu); }); So a parent entry never navigates, whatever its href. That's why every parent entry in menu.toml ships with no url: the click was never going to work. Giving the compliance entry a real URL and removing the "Overview" child left the overview page unreachable from the sidebar, which is worse than the duplicate row it replaced. The reverted work was verified by diffing rendered HTML, which can't observe a click handler attached at runtime. Making the parent link navigate needs either custom JavaScript to unbind that handler, or Foundation's submenuToggle option, which would require a URL for every parent entry in the site. Both are larger than this change and belong with the navigation work, not here. Signed-off-by: Kushal J <kushalj@progress.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces a new Solutions section to chef-web-docs, organized around customer outcomes rather than individual products, starting with a Chef Compliance solution.
Structure
Overview -> Solutions -> Overview(/solutions/) - landing page for all solutions (card grid), with Chef Compliance live and 7 other solution areas marked "Coming soon".Overview -> Solutions -> Compliance -> Overview(/solutions/compliance/) - Chef Compliance overview: workflow, common scenarios, and a benchmark coverage catalog.Overview -> Solutions -> Compliance -> {9 categories}- benchmark coverage tables (Operating Systems, Desktop/Client, Databases, Cloud, Containers/Kubernetes, Web Servers, Applications/Middleware, Virtualization, Network/Infrastructure), sourced from the internal "Chef Compliance - Current Support Coverage" catalog.This mirrors the existing
Download/Packages & Platformspattern:SolutionsandComplianceare non-clickable folder headings, each with a realOverviewchild page holding the content.Validation
markdownlint-cli2,vale, andcspellall pass locally and in CI.hugo server(pinned to v0.152.2 per this repo's CI).git commit --signoff), authored by Pradyumn Prabhu pradyumn.prabhu@progress.com.This is a draft to gather early feedback on IA/copy before final review.