Skip to main content

About this project

This is a project where I built an ecosystem of developer tools:

  • A CLI
  • An API
  • An SDK

And I built them because I wanted to understand how they work.

I've used CLIs, APIs, and SDKs before, and I document APIs at work. But I realized there was a part of the process I didn't fully understand: how they are built.

So I decided to find out for myself, and Beyond the Docs was born.

How it started​

Last December, while exploring ways to improve API documentation workflows, I had an idea for a personal project.

What if there was a CLI tool that could validate and improve OAS files? Not just check them for style, but validate they are complete, valid, and ready for downstream consumption?

That idea eventually became SpecGate, a Go-based CLI that enforces OpenAPI specification readiness. I'd never built a CLI before, so I had to learn Go and the Cobra CLI framework along the way.

Once SpecGate was working, I realized I didn't have a real OAS file to test it against. So I built a Django REST API for a fictional photography platform called Fstop and generated an OAS file to use with SpecGate.

SpecGate has a command called advise that uses OpenAI's Python SDK to make API calls to GPT-5-mini. While working on this command, I began to wonder how SDKs work and whether I could create one for the Fstop API.

I learned that SDKs can be generated from OpenAPI specifications, so I used Speakeasy to auto-generate a Python SDK from the Fstop API's OAS file.

And suddenly, I had a full ecosystem: an API, an OAS file, a CLI that validates it, and an SDK generated from it.

A diagram of the Beyond the Docs ecosystem

Why I built it​

As a technical writer, I spent a lot of time thinking about the user experience: what users need to know, where they might get stuck, how information should be organized, and how the documentation can support their journey through a product or tool.

But I don't usually have to understand how those tools are built. I can design effective API documentation without having built the API. But I wondered if learning how those tools are built could help give me a new perspective on technical writing.

By building these tools myself, I had to step outside my usual area of expertise and think about the technical decisions that shape the developer experience. And in doing so, I had more questions about the relationship between development and documentation:

  • What makes an API easy for developers to consume?
  • How does an OpenAPI specification become an SDK?
  • How do API design decisions affect the documentation developers rely on?
  • What's the relationship between API reference documentation and SDK documentation?
  • What makes a developer tool intuitive and useful?
  • Where does automation fit into the development and documentation workflow?

Building these three tools helped explore these questions.

This project is my way of getting hands-on experience with developer tools and workflows so I can bring that understanding back to my technical writing work.

What you'll find here​

  • Building: The developer tools I created and the decisions behind them
  • Documenting: How I designed documentation workflows for these tools
  • Reflecting: Lessons learned about developer experience, tooling, and documentation