# Documentation Pipeline Portfolio

> A working demonstration of an end-to-end technical documentation quality
> pipeline. Built by Diana Payton to show what modern, AI-era documentation
> practice looks like in a portfolio context — with running CI checks, custom
> Vale rules, docs-as-tests, and agent-facing documentation maintained by the
> same pipeline it describes.

## What this site is

This is a portfolio demonstration site, not a consulting site. Everything on
it — the pipeline configuration, the custom Vale rules, the OpenAPI spec, the
GitHub Actions workflows — was built to show a hiring manager what competent
documentation engineering looks like in practice.

## The pipeline

Four quality checks run automatically on every content change:

- Style and terminology linting (Vale) — runs on pull request, errors block merge
- Spell checking (codespell) — runs on pull request, any misspelling blocks merge
- External link checking (Lychee) — runs on push and every Monday at 8am UTC
- Docs-as-tests (Doc Detective) — runs on push to main, validates docs against the live site
- Front matter validation (docmeta) — runs on pull request, missing or malformed metadata blocks merge

## Custom Vale rules

Five rules were written from scratch beyond the standard Google style guide:

- Passive.yml: warns on passive voice ("was edited", "were deployed")
- Terminology.yml: errors on "utilize", "leverage", "spin up", "kick off"
- StackedHeadings.yml: warns when a heading immediately follows another
  heading with no prose between them — uses scope: text with a multiline regex
- Acronyms.yml: requires an acronym to be spelled out on first use, with an
  exception list for acronyms common enough to skip (API, HTML, URL, and
  similar)
- Headings.yml: enforces sentence-style capitalization in headings, with an
  exception list for proper nouns and product names (TypeScript, Kubernetes,
  macOS, and similar)

## Site sections

- [Introduction](/docs/intro): Site overview and the tooling stack (Vale, Doc Detective, docmeta, pipeline.md, GitHub Actions)
- [pipeline.md](/docs/pipeline): Full technical breakdown of every tool and design decision
- [Portfolio](/portfolio): Writing samples from Grafana Labs and Macrometa
- [Garden Companion API](/api): OpenAPI 3.1 spec rendered via Scalar
- [Blog](/blog): Posts on documentation systems and tooling decisions

## Key files in the repository

- .github/workflows/ — fourteen workflow definitions
- .vale/styles/Diana/ — five custom rules (Passive.yml, Terminology.yml, StackedHeadings.yml, Acronyms.yml, Headings.yml)
- .lychee.toml — Lychee configuration with exclusion rules
- docmeta.config.yaml, docmeta/showcase.schema.json — front matter schema: every published page needs a title, a description, and a last_reviewed date
- website/static/api/garden.yaml — OpenAPI 3.1 spec
- doc-detective/tests/ — Doc Detective test specifications

## About Diana Payton

Technical documentation leader with 15+ years of experience building
documentation functions from the ground up. Former Grafana Labs, Macrometa,
Thermo Fisher Scientific. Specializes in documentation systems for teams
navigating the shift to AI-assisted and agent-readable documentation.

https://www.linkedin.com/in/dianapayton/