Compliance Documentation

Compliance documentation is the living, traceable record of how systems, processes, and people meet regulatory, legal, or internal requirements. It matters most during audits, when a reviewer demands proof that a policy was implemented, monitored, and maintained — not just declared. This documentation is not a static PDF; it is a set of interlinked, versioned, and executable artifacts that define *what* compliance means and *how* it is achieved across the engineering lifecycle.

Creating and Maintaining Compliance Documentation

The core of compliance documentation lies in defining what a compliance requirement is, how it is met, and how evidence is collected and organized. Every requirement must be explicitly linked to a control, a policy, and a system.

Defining a Compliance Requirement

A compliance requirement is a statement that a system must satisfy a rule. It is described in a structured format:

---
id: C-0012
title: Data Retention for PII
policy: GDPR Article 5(1)(c)
control: Retention Schedule
status: active
applicable-systems: [user-service, billing-service, analytics-pipeline]
evidence-files:
  - /compliance/controls/C-0012/retention-schedule-v2.pdf
  - /compliance/controls/C-0012/audit-log-query.sql
  - /compliance/controls/C-0012/automated-checks.json
last-reviewed: 2024-04-15
reviewer: [email protected]
---

Data must be retained for at least 7 years after the last interaction with a user, including all personal identifiers, and must be recoverable within 24 hours of a request.

All data must be archived in a format that preserves metadata and is indexed by user ID and date.

This file, stored as C-0012.md in a Git repository under /compliance/controls/, is the primary source of truth. The id field is used across tools to link controls to tests, audits, and dashboards.

Linking Requirements to Evidence

Evidence is not merely a file; it is a proof that a requirement was fulfilled. Evidence is collected in three forms:

1. Manual evidence – a signed document, a meeting log, or a signed-off checklist.
2. Automated evidence – a script output, a query result, or a test report.
3. System-generated evidence – logs, audit trails, or metadata from a service.

Each evidence item is versioned and linked to the requirement via a evidence-files list. When a new audit begins, the compliance team generates a evidence-summary.json by scanning the entire /compliance/controls/ directory:

{
  "C-0012": {
    "status": "verified",
    "evidence": [
      {
        "path": "/compliance/controls/C-0012/retention-schedule-v2.pdf",
        "type": "manual",
        "verified-by": "[email protected]",
        "verified-on": "2024-04-15"
      },
      {
        "path": "/compliance/controls/C-0012/audit-log-query.sql",
        "type": "automated",
        "run-by": "[email protected]",
        "run-on": "2024-04-14T10:00:00Z",
        "result": {
          "rows": 1274,
          "duration": "2.1s",
          "query": "SELECT * FROM audit_log WHERE event_type = 'DATA_RETENTION_CHECK' AND timestamp > '2024-04-01'"
        }
      }
    ]
  }
}

This JSON is produced by a simple shell script executed by CI:

#!/bin/bash


set -euo pipefail

OUTPUT_DIR="./compliance/summary"
mkdir -p "$OUTPUT_DIR"

echo '{' > "$OUTPUT_DIR/evidence-summary.json"

first=true
for control_dir in compliance/controls/*; do
  control_id=$(basename "$control_dir")
  if [ "$first" = true ]; then
    first=false
    echo -n '  "'$control_id'": {' >> "$OUTPUT_DIR/evidence-summary.json"
  else
    echo -n ',\n  "'$control_id'": {' >> "$OUTPUT_DIR/evidence-summary.json"
  fi

  # Parse control metadata
  while IFS= read -r line; do
    key=$(echo "$line" | cut -d: -f1 | xargs)
    value=$(echo "$line" | cut -d: -f2- | xargs)
    if [[ "$value" == *"["* ]]; then
      # Array value
      value=$(echo "$value" | sed 's/^\[//' | sed 's/\]$//' | sed 's/, /", "/g')
      echo -n '"'$key'": ['"$value'"],' >> "$OUTPUT_DIR/evidence-summary.json"
    else
      echo -n '"'$key'": "'"$value"'",' >> "$OUTPUT_DIR/evidence-summary.json"
    fi
  done < <(grep -E '^[a-zA-Z-]+:' "$control_dir/README.md")

  # Add evidence entries
  echo -n '"evidence": [' >> "$OUTPUT_DIR/evidence-summary.json"
  # ... (loop over files in control_dir, add JSON objects)
  echo -n ']' >> "$OUTPUT_DIR/evidence-summary.json"
done

echo '}' >> "$OUTPUT_DIR/evidence-summary.json"

Versioning and Traceability

Each compliance document is versioned using Git. Every change to a control is a commit with a message that includes the id of the requirement:

git commit -am "C-0012: Update retention period to 7 years; add indexing requirement"

A compliance-changelog.md file is maintained at the root of the compliance directory, updated with every change:

## 2024-04-15
- C-0012: Data Retention for PII
  - Updated retention period to 7 years
  - Added requirement for index by user ID and date
  - Added query script as automated evidence
- C-0007: Consent Collection
  - Added field for consent timestamp in form
  - Added validation rule for consent withdrawal

## 2024-03-28
- C-0005: Secure Data Transmission
  - Added TLS 1.3 as required protocol
  - Added certificate rotation schedule

The compliance-changelog.md is used to produce a compliance release note, which is shared with auditors and stakeholders.

Review and Approval Workflows

Each compliance requirement must be reviewed and approved before being considered valid. The review process is managed via a pull request (PR) in Git.

When a new requirement is added, a PR is opened with the following structure:

## C-0012: Data Retention for PII

### Description
Data must be retained for at least 7 years after the last interaction with a user, including all personal identifiers, and must be recoverable within 24 hours of a request.

### Evidence
- [ ] /compliance/controls/C-0012/retention-schedule-v2.pdf
- [ ] /compliance/controls/C-0012/audit-log-query.sql
- [ ] /compliance/controls/C-0012/automated-checks.json

### Reviewers
- [ ] [email protected]
- [ ] [email protected]
- [ ] [email protected]

### Checklist
- [ ] Requirement matches policy
- [ ] Evidence is complete and accurate
- [ ] All applicable systems are listed
- [ ] Reviewer feedback addressed

Reviewers comment directly on the PR, using GitHub-style inline comments. When all reviewers approve, the PR is merged, and a status: verified field is added to the control’s metadata.

Embedding Documentation in Systems

Compliance documentation is not external; it is embedded into the systems it describes. Each service has a compliance.json file in its configuration directory:

{
  "controls": [
    "C-0001",
    "C-0005",
    "C-0012",
    "C-0021"
  ],
  "evidence": {
    "audit-log": {
      "query": "SELECT * FROM audit_log WHERE event_type = 'COMPLIANCE_CHECK' AND control_id = 'C-0012'",
      "schedule": "daily",
      "last-run": "2024-04-15T08:00:00Z"
    },
    "data-retention": {
      "script": "/opt/compliance/scripts/check-retention.sh",
      "config": "/etc/compliance/retention-config.json",
      "last-success": "2024-04-14T10:00:00Z"
    }
  },
  "status": "active",
  "last-synced": "2024-04-15T09:30:00Z"
}

This file is consumed by a compliance monitor that checks the status of each control and updates the compliance dashboard.

Generating and Distributing Compliance Reports

A compliance report is a summary of all active requirements, their status, and evidence. It is generated daily via a cron job:

# /etc/cron.daily/compliance-report
#!/bin/bash

set -euo pipefail

REPORT_DIR="/var/reports/compliance"
mkdir -p "$REPORT_DIR"

# Generate markdown report
cat > "$REPORT_DIR/compliance-report-$(date +%Y-%m-%d).md" << EOF
# Compliance Report: $(date --iso-8601)

## Summary
- Total controls: 142
- Active: 137
- Verified: 124
- Needs-review: 13
- Failed: 3

## Detailed Status
EOF

# Query each control
while IFS= read -r control_id; do
  control_file="/compliance/controls/$control_id/README.md"
  status=$(grep -E '^status:' "$control_file" | cut -d: -f2- | xargs)
  echo "### $control_id ($status)" >> "$REPORT_DIR/compliance-report-$(date +%Y-%m-%d).md"
  echo "" >> "$REPORT_DIR/compliance-report-$(date +%Y-%m-%d).md"
done < <(ls /compliance/controls/)

# Add evidence summary
jq -r '.[] | .evidence | .[] | .path' < "/compliance/summary/evidence-summary.json" >> "$REPORT_DIR/compliance-report-$(date +%Y-%m-%d).md"

# Convert to PDF
pandoc -f markdown -t pdf -o "$REPORT_DIR/compliance-report-$(date +%Y-%m-%d).pdf" "$REPORT_DIR/compliance-report-$(date +%Y-%m-%d).md"

The report is then distributed via email and published to a shared drive.

Managing Compliance Documentation in Practice

Common Failure Modes

• Unlinked evidence: A file exists but is not referenced in the control’s evidence-files list. The reviewer finds it, but it’s not formally part of the documentation.
• Out-of-sync metadata: A control’s status field is active, but the last-reviewed date is from six months ago. No one updates it when changes are made.
• Missing versioning: A new version of a retention schedule is uploaded, but the C-0012.md file does not reflect the new version number or update date.
• Orphaned evidence: A script is run and produces output.json, but the file is not committed to Git, nor is it listed in the control’s evidence-files.

Configuration Pitfalls

• Using id as primary key but not enforcing uniqueness: Two controls with id: C-0012 exist, causing confusion and duplication.
• Misplacing the compliance-changelog.md: It is not updated with every change, leading to a stale changelog.
• Over-automating without validation: A script runs daily and generates an evidence file, but the output is never inspected. A null result in a query is accepted as success, but the duration field is missing from the result.

Key Decisions and Tradeoffs

• Flat vs hierarchical documentation: A flat directory of control files is simpler to manage but harder to discover. A hierarchy (/compliance/standards/gdpr/controls/C-0012.md) adds structure but requires more setup.
• Manual vs automated evidence: Manual evidence is easier to create but slower to update. Automated evidence is fast and repeatable but requires scripting and maintenance.
• Single vs multiple versioning systems: Using Git for all documentation is consistent but adds cognitive load. Using Git for controls and a database for evidence introduces complexity but allows richer querying.

Tools and Patterns

The core tooling is built around standard Unix utilities and widely supported formats:

• Git for version control, branching, and pull requests.
• YAML/JSON for structured metadata and configuration.
• SQL for evidence queries and reporting.
• Shell scripts for automation and orchestration.
• pandoc for document conversion (Markdown → PDF, HTML, etc.).
• Systemd for scheduled compliance jobs (compliance-monitor.service, compliance-report.timer).

No tool is assumed to have a unique interface. The compliance.json file is a standard format, consumed by any service. The evidence-summary.json is a shared artifact used by dashboards, audits, and reporting pipelines.

All documentation is discoverable via a simple web server or a shared file system. A compliance/ directory is served over HTTP, with a index.html that lists all controls and provides links to their files.

Compliance documentation is not a deliverable; it is a process. It is the artifact that tells the story of how compliance is lived in engineering — not just documented, but enacted.

This page was rewritten on 18 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.