Skip to main content
Version: v2.1 (latest)

Introduction

This site is a roadmap for building a docs-as-code pipeline for AI product documentation in regulated financial services.

It walks through every decision — tooling, content structure, CI/CD, deployment — using a worked example: the fictional Multi-Asset Risk System, a suite of risk management tools for front office, risk, and collateral professionals to analyse portfolios, manage exposures, and ready themselves for any turn of events.

The product is modelled on real systems used by global banks. The fictional context lets the pipeline demonstrate domain-realistic content — regulatory references, haircut schedules, SHAP explainability, audit trail requirements — without disclosing proprietary information.

Who this is for​

This site is written for:

  • Technical writers moving from traditional API docs into AI product documentation, especially in regulated industries
  • Engineering leads scoping a docs-as-code setup for a team that ships AI features
  • Product managers designing Definition of Done criteria for AI features that must meet audit and compliance obligations
  • Documentation teams at financial services firms who need a template that handles model versioning, regulatory audit trails, and RAG-ready content structure

You do not need deep financial services experience to follow the roadmap. The worked example introduces the regulatory concepts as they become relevant.

What you will build​

By the end of the roadmap, you will have a repository that:

  • Publishes versioned documentation to GitHub Pages on every merge to main
  • Lints prose against financial-services writing conventions before merge
  • Validates OpenAPI specs against OpenAPI 3.1 schema and custom rules
  • Produces an interactive API reference from the spec
  • Structures every document for RAG retrieval with jurisdiction-aware metadata
  • Includes AI model cards with regulatory audit trail specifications
  • Tracks model versions separately from software versions

The finished pipeline is visible on this site. The source is at github.com/ivanwalsh/ai-fintech-docs-pipeline.

Why this is different from a standard Docusaurus setup​

Most documentation pipelines are built for software versioning. This pipeline is built for AI product documentation in financial services, which has three additional requirements that standard setups do not address.

Model-release versioning​

AI models in financial services have discrete versions with regulatory significance. An auditor may need to know exactly what documentation was live when a decision was made by model version 2.0.0 in March 2025. The pipeline is configured to snapshot documentation per model release, not per software release.

RAG-ready content structure​

Documentation that feeds a retrieval-augmented generation pipeline needs to be structured so AI systems can retrieve it accurately. Every document includes regulatory_scope frontmatter for jurisdiction-aware retrieval filtering, H2-level semantic chunking, last_reviewed dates that trigger re-indexing, and description fields calibrated for retrieval ranking.

Regulatory audit trail​

The documentation treats the audit trail as first-class content. The worked example API logs every inference with a tamper-evident input_hash and inference_id. The model card documents the retention policy (seven years, FCA SYSC 9.1). The chatbot integration guide specifies how inference_id must be included in chatbot session audit logs.

This is not typical in software documentation. It is specific to regulated financial services AI.

How to use this site​

The Build the pipeline section walks through the roadmap in order. Each page is a discrete step — you can complete them in sequence or jump to the one that matches your current gap.

The Worked example section contains the Multi-Asset Risk System documentation itself: quickstart, chatbot integration guide, AI model card, and changelog. Treat these as templates you can adapt for your own product.

The Blog covers related topics: MCP server documentation, AI-ready content patterns, and lessons from building the pipeline.

Start here​

If you are new, start with the Pipeline overview to see how all the parts fit together. Then follow the roadmap in order, beginning with Project setup.