diff --git a/.aar_doc.yml b/.aar_doc.yml
new file mode 100644
index 00000000..492f023c
--- /dev/null
+++ b/.aar_doc.yml
@@ -0,0 +1,44 @@
+output_template: |
+  <!-- BEGIN_ANSIBLE_DOCS -->
+
+  ## Supported Operating Systems
+
+  {%- for platform in metadata.galaxy_info.platforms %}
+  - {{ platform.name }}
+    {%- if "versions" in platform %}
+    - {{ platform.versions | default([]) | join(', ') }}
+    {%- endif %}
+  {%- endfor %}
+
+  ## Role Variables
+  {% for entrypoint in argument_specs.keys() %}
+  {%- set path, options=entrypoint_options[entrypoint][0] -%}
+  {%- for name, details in options.items() |sort() %}
+  - `{{ name }}`
+    - Default: `{{ details.display_default }}`
+    - Description: {{ details.display_description }}
+    - Type: {{ details.display_type }}
+    - Required: {{ details.display_required }}
+  {%- endfor %}
+  {%- endfor %}
+
+  ## Dependencies
+
+  {%- if ("dependencies" in metadata) and (metadata.dependencies | length > 0) %}
+  {%- for dependency in metadata.dependencies %}
+  - {{ dependency }}
+  {%- endfor %}
+  {%- else %}
+
+  None.
+  {%- endif %}
+
+  ## Example Playbook
+
+  ```
+  - hosts: all
+    roles:
+      - name: {{ role }}
+  ```
+
+  <!-- END_ANSIBLE_DOCS -->
diff --git a/.github/workflows/roles-readme.yml b/.github/workflows/roles-readme.yml
new file mode 100644
index 00000000..4651b1d6
--- /dev/null
+++ b/.github/workflows/roles-readme.yml
@@ -0,0 +1,47 @@
+---
+name: create roles readme
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches: [master]
+    paths:
+      - 'roles/**/meta/argument_specs.yml'
+  pull_request:
+    branches: [master]
+    paths:
+      - 'roles/**/meta/argument_specs.yml'
+
+jobs:
+  readme:
+    name: create roles readme
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        roles:
+          - mysql_hardening
+          - nginx_hardening
+          - os_hardening
+          - ssh_hardening
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - name: Install aar_doc
+        run: pip3 install aar_doc
+
+      - name: Run aar_doc
+        run: aar_doc roles/${{ matrix.roles }} markdown
+
+      - name: Push README
+        uses: github-actions-x/commit@v2.9
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          push-branch: ${{ github.head_ref ?? github.ref_name }}
+          commit-message: 'update ${{ matrix.roles }} readme'
+          files: roles/${{ matrix.roles }}/README.md
+          rebase: true
diff --git a/roles/ssh_hardening/meta/argument_specs.yml b/roles/ssh_hardening/meta/argument_specs.yml
index da60c1b6..44b39891 100644
--- a/roles/ssh_hardening/meta/argument_specs.yml
+++ b/roles/ssh_hardening/meta/argument_specs.yml
@@ -221,7 +221,7 @@ argument_specs:
       ssh_client_hardening:
         default: true
         type: bool
-        description: '`false` to stop harden the client.'
+        description: Set to `false` to stop harden the client.
       ssh_client_compression:
         default: false
         type: bool
@@ -256,7 +256,7 @@ argument_specs:
       ssh_server_hardening:
         default: true
         type: bool
-        description: '`false` to stop harden the server.'
+        description: Set to `false` to stop harden the server.
       ssh_server_match_address:
         default: ''
         description: Introduces a conditional block. If all of the criteria on the