Skip to content

docs: resolve live link audit findings #2254

Description

@sbaum1994

Problem

A live audit after P5 publication found link failures that local Fern navigation checks do not detect. Audit source: main 7e7f41d2586c7db401f8b23f520643d7ed770b6d. Audit run and JSON artifact report 198 pages, 802 links, and 11 findings. Direct HTTP checks and current rendered pages distinguish two confirmed broken destinations from authentication requirements, an endpoint example, and stale scanner references.

Confirmed repairs

Source Broken destination Proposed correction
docs/ngc-managed/cluster-management/kai-scheduler.md, download template /nvcf/overview/samples/kai-scheduler-queues.yaml returns 404. PR #2253 pins the download to its immutable raw GitHub resource at the audited main commit. HTTP 200 and byte-for-byte comparison with the source passed.
docs/compute-plane/cluster-management/topology-aware-scheduling.md and its retained 1.0.0 archive Dynamo v1.4.1/kubernetes-deployment/scale/topology-aware-scheduling returns 404. PR #2253 repairs both sources using the version-matched topology guide. HTTP 200 and article-content verification passed.

Scanner findings requiring different treatment

  • Four NGC URLs return 401 to the unauthenticated scanner: organization profile, service keys, API-key setup, and legacy API-key setup. These require an account; do not call them confirmed missing pages.
  • The Grafana OTLP URL in docs/ngc-managed/observability.md is an endpoint example, not a browser documentation page. PR ci(docs): block merges on broken links in changed Markdown #2253 renders it as code so it does not look like a navigable reference.
  • Four scanner references still point to raw.githubusercontent.com/NVIDIA/nvcf/main/docs/user/samples/.... Main, both frozen docs branches, and current live HTML/Markdown use the corrected docs/v0.5/samples/... paths. The corrected URLs work. Reconcile the scanner's stale/orphaned references instead of changing already-correct archive content or adding a blanket ignore rule.

Acceptance

  • Verify the two replacement destinations and the exact sample contents.
  • Repair current sources, preview the result, and publish stable corrections through the next docs patch. Do not rewrite published docs/releases/1.0.1 or docs/releases/1.0.2.
  • Handle the retained archive reference explicitly in the review; preserve historical content/version identity.
  • Re-run the live audit, separating real 404s from access requirements and stale records. Keep its full report with the validation evidence.

Current-source fixes and CI: #2253. The hosted preview passed rendered-link checks for current and retained historical Dynamo pages, the KAI download, and the OTLP example. Publication and scanner reconciliation remain open. Relates to #2214.

Implementation status

PR #2253 now checks proposed Markdown changes inside the existing required docs job. It includes full Fern internal/Development validation, external HTTP checks for changed .md/.mdx files, failure propagation, and a downloadable report. The weekly and post-publication live audits were removed at the requested scope change. Four exact interactive NGC account pages are documented exceptions; stale Fern live-index records are not inputs to this source-based gate.

PR #2256 includes the repairs in docs-only release 1.0.3. The protected branch already exists at 6443f718df3808177eb151a67576b75c939044e9; older release refs are unchanged. The canonical preview and its validation run passed. Production publication still depends on reviewing and merging #2253, then retargeting and merging #2256.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions