Skip to content

[docs-scanner] Remediation docs reference incomplete features in comments #24925

@docker-agent

Description

@docker-agent

File: content/manuals/scout/policy/remediation.md

Issue

The file contains HTML comments referencing features that are documented as working but are actually not yet supported:

In the "No provenance attestations" section:

<!--
  TODO(dvdksn): no support for the following, yet

  When provenance attestations are unavailable, Docker Scout provides generic,
  best-effort recommendations in the remediation side panel. These
  recommendations estimate your base using information from image analysis
  results. The base image version is unknown, but you can manually select the
  version you use in the remediation side panel. This lets Docker Scout evaluate
  whether the base image detected in the image analysis is up-to-date with the
  version you selected.

  https://github.com/docker/docs/pull/18961#discussion_r1447186845
-->

In the "GitHub integration enabled" section:

<!--
  TODO(dvdksn): no support for the following, yet

  Enabling the GitHub integration also allows Docker Scout to visualize the
  remediation workflow in the Docker Scout Dashboard. Each step, from the pull
  request being raised to the image being deployed to an environment, is
  displayed in the remediation sidebar when inspecting the image.

  https://github.com/docker/docs/pull/18961#discussion_r1447189475
-->

Why this matters

These comments indicate that the current documentation may be incomplete or misleading. The "No provenance attestations" section currently states that compliance is "undeterminable" without provenance, but the commented-out text suggests there should be best-effort recommendations. Similarly, the GitHub integration section may be missing information about workflow visualization.

Readers may expect features that don't exist, or the documentation may be missing helpful information about workarounds or current capabilities.

Suggested fix

Either:

  1. Implement the features described in the comments and uncomment the text, or
  2. Remove the TODO comments if the features won't be implemented, or
  3. Add a note to the documentation explaining the current limitations and planned future enhancements

The comments reference specific GitHub PR discussions that may provide context for resolving this.


Found by nightly documentation quality scanner

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions