· API Documentation  · 2 min read

Building a Sustainable API Documentation Pipeline

When engineering used OpenAPI and AWS publishing required a different model, I researched and adopted the internal process—creating the first external API guide and a reliable way to keep it current.

When engineering used OpenAPI and AWS publishing required a different model, I researched and adopted the internal process—creating the first external API guide and a reliable way to keep it current.

Overview

I created the first external API guide for a forensic data archiving solution used by government and public-sector customers to securely store and retrieve digital evidence.

The work required reconciling OpenAPI outputs from engineering with Amazon’s internal documentation service model, authoring the full API reference, and designing a repeatable publishing process so future updates could be generated with minimal rework.

The Challenge

  • Different models: Engineering maintained OpenAPI, while AWS publishing depends on a custom internal model that doesn’t align directly.
  • No existing documentation: The API guide had to be built entirely from scratch, compliant with AWS editorial and accessibility standards.
  • Limited SME availability: Engineering support was limited, so I worked from models and code to ensure accuracy.
  • Ongoing maintenance risk: Without a bridge between models, every release would require manual rebuilds.

My Approach

1. Bridge OpenAPI to the internal model

  • Mapped operations, parameters, and responses from OpenAPI into the AWS service-model structure.
  • Established a translation workflow allowing the engineering model to feed the publishing pipeline automatically.
  • Worked with the lead engineer to validate mappings and ensure future compatibility.

2. Write and structure the guide

  • Authored the core API guide from the ground up: onboarding, authentication, request/response conventions, and error handling.
  • Standardized endpoint descriptions and examples for clarity and consistency.
  • Organized content around customer workflows (uploading evidence, retrieving records, verifying integrity) instead of raw endpoints.

3. Editorial and compliance alignment

  • Ensured compliance with AWS style, terminology, and accessibility requirements.
  • Provided editorial feedback to engineering on naming and parameter clarity.
  • Verified that the published output rendered correctly in the internal pipeline.

4. Collaborate under constraints

  • Partnered closely with a lead engineer to validate examples and workflow accuracy.
  • Minimized review overhead by testing API calls directly when SME input wasn’t available.

Outcome

  • Delivered a complete, compliant API guide for launch.
  • Built a repeatable publishing flow where future updates generate automatically from the internal model.
  • Reduced documentation update cycles from weeks to hours.
  • Established a sustainable hybrid model—automated where possible, human-authored where context matters—that other teams later replicated.

Reflection

This project reinforced that clear documentation depends on infrastructure as much as language.

By connecting engineering outputs to AWS’s internal publishing system, I turned a one-time deliverable into a living documentation process that evolves with the product.

Share: