Documentation Quality Gate

Scope

This document describes the lightweight documentation quality gate used in this technical documentation hub.

The gate is designed for public-safe portfolio documentation, reusable technical notes, operational runbooks and governance-oriented Markdown documents.

It checks for documentation risks that are easy to introduce during fast iteration: missing boundaries, accidental credential-like material, privacy-sensitive identifiers and unscoped production, enterprise or certification language.

Non-goals

This gate is not an enterprise DLP system, a full GRC platform, a legal compliance review, a semantic security classifier, a secret-scanning replacement or an automated approval authority.

This is not production-ready assurance. The gate does not prove that a document is complete, correct, compliant or safe for every audience.

Human review is still required before promoting material from private working notes into public-safe documentation.

Public/private boundary

This document is public-safe.

It describes the control model, validation intent and expected documentation style. It does not include private evidence, customer material, credentials, internal infrastructure details, production data, security findings or environment-specific secrets.

Purpose

The quality gate exists to make documentation safer and more reviewable before merge.

It enforces a simple principle:

Public-facing technical documentation must explain its scope, boundaries and non-goals before it makes technical or governance claims.

The gate keeps the repository aligned with the broader documentation model:

• documentation should reduce ambiguity
• public examples must stay separate from private evidence
• production, enterprise and certification language must be scoped
• operational notes should record failure modes without turning them into exaggerated incidents
• AI-assisted documentation should remain inside explicit human-controlled boundaries

What the gate checks

The validator currently focuses on three risk classes.

1. Credential and identifier risk

The gate hard-fails when documentation appears to include credential-like material such as:

• private key blocks
• API keys, access tokens or client secrets
• credential or certificate identifiers that are not explicitly omitted or redacted
• Microsoft credential-style identifiers

This is not a complete secret-scanning engine. It is a focused documentation safety net.

2. Overclaiming risk

The gate checks selected high-risk wording, including:

• production-ready
• enterprise-ready
• certification / certified wording

These terms are not banned, but they must be balanced by an explicit boundary statement.

The goal is not to remove ambition from documentation. The goal is to prevent portfolio or lab documentation from implying maturity, certification or production status that is not being claimed.

3. Documentation boundary risk

Markdown files under docs/ are expected to include at least one explicit boundary-style section, such as:

• ## Scope
• ## Non-goals
• ## Public/private boundary
• ## Public/private documentation boundary
• ## What this is not
• ## What not to claim
• ## Safe seniority framing

Short notes and README files are handled separately to avoid turning every small document into heavy compliance paperwork.

Failure mode example

A local WordPress lab port collision note was added after two local portfolio labs attempted to use the same localhost port.

The first version correctly documented the observation, root cause and corrective action, but it did not include an explicit documentation boundary section.

The quality gate failed with a documentation-boundary error.

The fix was to add:

## Scope
## Non-goals
## Public/private boundary

After that, the document passed validation.

The important lesson is that the gate does not exist only to catch catastrophic leaks. It also forces routine operational notes to state what they are, what they are not and what they do not reveal.

How to fix a failed document

When the gate fails, prefer a small documentation correction instead of bypassing the gate.

A good fix usually adds or improves one of these sections:

## Scope

What this document covers.

## Non-goals

What this document does not define, claim or replace.

## Public/private boundary

What information is safe to publish here and what must remain outside the document.

Keep the fix proportional. Do not turn a short operational note into an enterprise compliance policy unless the document actually needs that level of detail.

How to run locally

From the repository root:

python tools/validate_documentation_quality.py

Expected result:

DOCUMENTATION QUALITY GATE: PASSED

CI workflow

The GitHub Actions workflow is located at:

.github/workflows/documentation-quality-gate.yml

The workflow runs on Markdown documentation changes and on manual dispatch.

Design principles

The quality gate is intentionally:

• lightweight
• deterministic
• readable
• CI-friendly
• conservative around public-safe documentation
• limited to documentation risk, not full security assurance

The gate is useful because it is small enough to understand and strict enough to change behavior.

Known limitations

The gate is regex- and structure-based.

It does not understand all context, detect every possible secret, assess legal compliance, prove documentation correctness, replace human review or determine whether a technical implementation is secure.

It should be treated as a guardrail for documentation hygiene and public-safe portfolio governance, not as a complete compliance control.

Operational value

The gate gives a clear signal during review:

Documentation is not merged just because it is well-written.
It must also be scoped, bounded and safe to publish.

That is the intended control behavior.