theforeman/foreman-documentation

Fix up style in Managing Security Compliance

Open

#4,214 opened on Sep 4, 2025

 (0 comments) (0 reactions) (1 assignee)SCSS (113 forks)auto 404
good first issue

Repository metrics

Stars
 (25 stars)
PR merge metrics
 (PR metrics pending)

Description

These issues were found during the review of https://github.com/theforeman/foreman-documentation/pull/4201. That PR was focused solely on addressing Vale issues from asciidoctor-dita-vale so I'm recording them here so that they are not lost:

  1. guides/common/modules/con_configuring-compliance-policy-deployment-methods.adoc

This sounds off to me: the first sentence states "use one", then second "you will".

Maybe reword to "Configure a method to deploy compliance policies to host. This is required to create a compliance policy." I am unsure if the second part is even necessary.

  1. guides/common/modules/proc_configuring-project-for-ansible-compliance-policy-deployment.adoc

This lacks an entry point: It's either scp'ing the Ansible role onto Foreman Server, or, if you have installed ansiblerole-foreman_scap_client via RPM, then it's Web UI, Ansible > Roles.

  1. All files: Drop {context} from all IDs.

  2. All files: Make sure section headings in external links comply with sentence case.

  3. guides/common/modules/proc_configuring-project-for-puppet-compliance-policy-deployment.adoc

"Ensure Puppet is enabled." is a prerequisite

  1. guides/common/modules/proc_configuring-project-for-puppet-compliance-policy-deployment.adoc

"Import the Puppet environment that contains the foreman_scap_client Puppet module." also lacks a proper entry point.

  1. guides/common/modules/proc_listing-available-scap-contents-using-cli.adoc

"* Run the following Hammer command on {ProjectServer}:" should be "* List SCAP contents on {ProjectServer}:"

  1. guides/common/modules/proc_searching-compliance-reports.adoc

In .Search query examples: I would expect an empty line between each paragraph and code block.

  1. guides/common/modules/proc_uploading-additional-scap-content-using-cli.adoc

"Note that [...]": AFAIK it's either an admonition or we drop "note that".

  1. guides/common/modules/proc_uploading-additional-scap-content-using-cli.adoc

". Run the following Hammer command on {ProjectServer}:" should be ". On {ProjectServer}, upload the additional SCAP contents:"

  1. guides/common/modules/proc_uploading-additional-scap-content-using-cli.adoc

"$ hammer scap-content bulk-upload --type directory " should be split into two lines

  1. guides/common/modules/proc_uploading-additional-scap-content-using-web-ui.adoc

"= Uploading additional SCAP content using {ProjectWebUI}" This seems to be the only instance of "SCAP content" opposed to "SCAP contents".

Contributor guide