Articles on API design, documentation, and developer experience from the ReadMe team.
Docs & AI
Mapping Code Changes to Documentation Impact
An AI writer is only as good as its ability to figure out which doc pages a code change affects. The mapping is the hard part.
Why an AI Documentation Agent Needs Your Style Guide
An agent that doesn't know your style guide produces output that has to be rewritten. An agent that knows it produces output you can ship.
Designing the Review Workflow for AI-Generated Documentation
Auto-merging AI drafts into your docs is how trust dies. A two-stage review keeps speed without giving up quality.
Using an AI Agent to Rewrite Documentation for Clarity
Generic AI invents. A docs-grounded agent rewrites. The difference is what the model knows before it starts.
Comparing Ways to Give an API to an LLM
Spec-in-prompt, retrieval, function calling, and MCP. Trade-offs and when to pick each.
How an AI Writer Detects Documentation Drift from a Pull Request
A PR-triggered AI writer reads the diff, decides whether any docs are affected, and drafts the update. Here is what the loop actually does.
Measuring How Many Past Support Tickets Your Docs Could Have Answered
A retrospective evaluation that replays resolved tickets against the current docs and reports what would have been self-serve.
Common Documentation Patterns That Cause Agents to Fail on an API
A short catalog of doc patterns that work for humans but break agents, with a fix for each.
Turning Support Tickets into Documentation Updates with an LLM in the Loop
A simple workflow that turns resolved tickets into draft doc updates, without taking humans out of the loop.
What LLMs Tend to Hallucinate When API Docs Are Incomplete
A checklist of the most common invented details, useful when reviewing a reference for gaps.
How Stale Documentation Affects Token Usage and Agent Behavior
When docs lag behind the API, agents do not just fail. They retry, escalate, and burn tokens trying to recover.
Using Your API Docs as an Evaluation Set for LLMs
Every code example in your docs is a task and an expected answer. Score how well a model uses them and you have a working benchmark for both the model and the docs.
GEO/AEO
Building Doc Pages That Survive Being Chunked
An AI engine rarely reads the whole page. A few patterns keep your content useful when only one section gets retrieved.
Schema.org Markup for API Docs in the Age of AI
A short tour of the schema types worth adding to API docs, why they matter for AI engines, and how to keep them in sync with the page.
How llms.txt Works, and What to Put in One for an API
A short field guide to writing an llms.txt for a developer-facing product, plus a sample.
What GEO and AEO Mean for Developer Documentation
A primer on Generative Engine Optimization and Answer Engine Optimization, and how the practice applies to API docs specifically.
Optimizing Docs for ChatGPT, Claude, and Perplexity
Each engine finds and reads your docs in a slightly different way. The differences matter when you want to show up on a specific surface.
How Agents Pick Which Version of Your Docs to Read, and How to Influence It
Stale doc versions reach agents through training data, search caches, and version routing. Each has a different way to push them toward current docs.
Writing Documentation That Works for Both Humans and Language Models
There is no separate style for AI-friendly docs. The same things that make a reference clear for a careful reader make it usable for a model.
API Tips
MDX Cheat Sheet and Quick Reference Guide
Good technical documentation tells and shows users how to use your software. MDX does a great job at the “show” part of documentation by allowing writers to embed interactive examples within Markdown documents. But MDX syntax isn’t always straightforward. In this article, we will review an MDX cheat sheet to help you with common use
MDX vs Markdown: Which One Should Your Team Use?
Your tech lead keeps asking to migrate your documentation from Markdown to MDX. They say that MDX adds the interactivity and functionality your users are demanding, without impacting performance or adding overhead. So, should your team transition from Markdown to MDX? And how do you do that? We’ll break all of this down in this
API Design: Best Practices and Pitfalls
Most developers have struggled working with poorly built or documented APIs. The common scenario goes like this: your product manager decides to leverage a third-party tool to speed up development, but the team suffers due to a bad API design. How do you know that an API is poorly designed? Common signs include mixing endpoint
Automated API Documentation: Everything You Should Know
API documentation helps developers understand and use APIs effectively. With automation, it’s easier to generate accurate and up-to-date reference materials. But some parts of documentation, like guides and tutorials, still require a human touch. In this article, you’ll learn about the components of API documentation and the challenges of automation, as well as discover tools that streamline
Bidirectional Sync: What Is It & How Does It Improve Collaboration
Think about any initiative (no matter how small) at your organization. Chances are good the work required multiple people using many, different tools. The importance of collaboration between people on a team is generally well understood; others may be able to see things you don’t and help you improve in new ways. But what about
How to Create API Documentation That Works for Every Developer
Most API documentation treats every developer the same way. You land on a “Getting Started” guide, move onto the authentication setup, and scroll through endpoint references. This one-size-fits-all approach to API documentation assumes every developer needs to learn your API from scratch. However, this isn’t how every developer uses your API. A developer making their
How to Create Helpful Error Messages in Your API Documentation
Picture this: It’s late at night and a developer keeps getting the same message when their API call fails. “Invalid request format” plays over and over again on their screen. However, there’s no explanation of what’s wrong. When something breaks, good API documentation should help developers understand three things: what went wrong, why it happened,
How to Make API Documentation More Interactive
Imagine a developer spending hours trying to implement your API. They dig through pages of documentation, yet can’t find the code they need. Finally, they write their own implementation through trial and error. Now multiply that frustration by thousands. That’s thousands of developers spending countless hours creating the same code snippets. Code you could have
Adopting Coding Standards Within a Large Codebase
Over the past month here at ReadMe, we’ve doubled the size of our engineering organization (…psst) and one thing that we quickly realized was that each of us have our own coding styles. This unfortunately was starting to result in comments on pull requests like, “Indent this line a few more characters so it’s consistent.”
A Visual Guide to What’s New in Swagger 3.0
Over the past few years, Swagger 2 has become the de facto standard for defining or documenting your API. Since then, it’s been moved to the Linux foundation and renamed to OpenAPI Spec. Version 3 has been in the works for a while, and it’s finally feature complete! Here’s a guide to what’s changed, and how
API Workflow Automations with Josue Negron of OneTrust
From high school entrepreneur to his current position, Josue has been working in tech for most of his life. As a Senior Principal Product Solutions Architect in the R&D organization at OneTrust, his first priority after being hired was to improve their APIs and developer experience. In addition to finding a vendor for their API documentation,
Basic OAS Server Variables Support in API Explorer
Update (Feb 18th, 2022): We’ve since shipped support for enums and you can now manually enter Server Variables via <input>. We’ve updated the content below to reflect this! OAS 3 introduced the concept of Server Variables. This allows you to configure changeable parts of your API’s URL. Here’s an example from the spec: This tells your
Best Practices for Writing API Docs and Keeping Them Up To Date
Developers respect clean, simple code. We have to be experts at finding ways to do more with less. And while that skill set is highly valued in development, it doesn’t always transfer over to writing great documentation. API documentation has to be more than bare necessities like methods and endpoints. It needs examples, summaries and
Combining API Metrics with API Error Docs
If you don’t know about API Error docs, read our previous post: Introducing API Error Docs. If you’re using our API Metrics product, this knows about all of the types of error that your API may produce and will assign errors to logs that come in if they’re of a given error type. This gives you two things:
Documenting Microservices in ReadMe
Many companies are breaking larger codebases into microservices, so different teams can work on parts of the site at different paces. They’re like APIs, except for an internal audience. Like any API, they need to be documented! While ReadMe is heavily used for large external projects, many of our customers are using it to document
Enterprise API Docs, What’s the Difference?
When I started at ReadMe four years ago, we had two plans: our Startup ($99) and Business ($399) tiers. As the first sales, marketing, and growth hire, my goal was to get more people to use ReadMe (and of course grow revenue). We already had thousands of paying customers building out easy-to-consume API documentation in
Exploring APIs, not Documentation
Hi Everybody! We’ve been working crazy hard to smooth out the API Explorer feature in ReadMe.io. We believe the optimal way to learn about an API is to interact with it rather than read about it in a massive wall of text. It should be easy to see how an API works, how the headers are
Workflow: Generating an OAS File From Your Code
OAS/Swagger provides us with a standardized way to document APIs, giving us a format which can be accepted by a multitude of tools to produce (largely) the same results. This is great! Open formats mean that we save time by not reinventing the wheel and every company creating its own standards. OAS files are only
How to Increase Your API Users
The Basics. What’s the point of building an API if nobody uses it? In the API world, the saying “If you build it they will come,” absolutely doesn’t hold true. As a matter a fact, if you build an API without marketing, explaining, and documenting it well, you’re on your way to getting lots of
I Hated Writing Documentation so I Founded a Company
People tell you to start a company around doing what you love. I founded a company to stop doing what I hated, documentation. I started my career as a developer at Mozilla working with PHP, before rising through the ranks to Python. After I decided to leave Mozilla, I did a lot of freelance development work
Jamstack Attack! Static Sites, Dynamic APIs, and a Killer DX
What is the Jamstack? “Maybe like a Jam Session. … I’m picturing a group of people jamming out (musically) in a garage or warehouse space.”, Owlbert, guess #5 The Jamstack (originally stylized JAMstack) is a way of building web applications that extends the benefits of “static sites”, emphasizing their true dynamic potential with APIs. Originally introduced as a concept
Making Better Use of Heroku’s Logging Firehose
This past month at ReadMe has been quite productive! We hosted a 24 hour API radio station, deployed a huge v6 of our API explorer, reimagined our Markdown engine, and released an app on Glitch showcasing how we’re able to demo Developer Metrics. What better time is there than now to tackle a longstanding project that completely rearchitects how we store,
Meet the Personalities Behind Your Docs’ Personalization
I am not a technical person. I’ve gotten a lot more so thanks to spending my days surrounded by highly technical people at ReadMe, but my lack-of-technical expertise was actually one of the reasons I was drawn to ReadMe. While developers make up the majority of people who see ReadMe’s developer platforms in the wild, I’ve always
Precision With Every Pixel
This is a guest blog post by the über-talented Amy Devereux. She’s been helping ReadMe make all things pretty, and is the designer behind 365cons.com. As you may have noticed, we use a lot of icons here at ReadMe! They’re helpful to succinctly visually inform and also just to make things more fun to look at. While
Reimagining ReadMe’s Markdown Engine
Migration Guides & Documentation→ If you’ve worked on any technical docs recently, you’ve almost definitely written Markdown. Love it or hate it, it’s the closest thing to a standard in terms of how we document our code. Jeff Atwood explains its dominance succinctly: Markdown is the worst form of markup, except for all the other forms of
The Best REST API Template
We tend to set a low bar when it comes to documenting our APIs. Developers can stomach poring over dense docs for a product that they’re interested in using, such as Google Maps or Twitter. Spending hours, days, weeks and falling into a support-searching rabbit-hole on Stack Overflow is practically an industry standard. But what
Upgrading React to v16 and Enzyme to v3
A couple of weeks ago React v16 was released with some exciting new features including returning arrays from render() functions (no more wrapping <divs>!), better server side rendering and performance improvements. Read more here: https://reactjs.org/blog/2017/09/26/react-v16.0.html We’re not yet using React on the main ReadMe site, but we are on one of our smaller projects which will soon be integrated
Using async/await in Node.js 7.6.0
Last week saw the release of Node.js v7.6.0 which contained (amongst other things) an update to v8 5.5 (Node’s underlying JS engine). This v8 release includes a brand new language feature: async functions. Utilising this new feature is done through 2 new keywords: async and await. Async functions are not new in the JS world and it has
Writing a Cron Job Microservice With Serverless and AWS Lambda
We recently had a situation where we needed to create a new cron job to fetch all users from our database who are coming to the end of their trials and insert them into our customer.io database. Cron jobs are easy to write, but difficult to set up. You can edit /etc/crontab on the server; if you’re
API Specifications 101: OpenAPI & Beyond
Written by: Chris Von See API specifications (machine-readable descriptions of an API’s structure and behavior) can boost API development productivity… if only API publishers would use them. Imagine you’ve been tasked with integrating a new third-party service into your company’s application. You go to the vendor’s developer portal, create an account, and hit the documentation,
GraphQL vs. REST: Which is best?
Written by: John Hurd GraphQL and REST APIs are both powerful tools to let users and programs access information. But how do you decide between the two? What kind of projects would be better solved by a GraphQL API? What about a REST API? In this article, we’ll provide a framework to help you decide
SDK vs API: Which One Should You Provide to Developers?
Written by: Brant Partington Developers are the lifeblood of your tech ecosystem. If they can’t use your tools easily, your brilliant functionality might go unused. The tools you offer, like APIs or SDKs, shape how developers interact with your services and whether they stick around. Understanding the difference between APIs and SDKs, and knowing when to offer
API Authentication Methods for OAS Security🛡️
What keeps you up at night as an API developer or professional? According to Postman’s State of API Report 2023, over 40,000 developers and API professionals identified “improper authentication, authorization, or access control” as the top API security risk for their organization. Obviously, picking the appropriate API authentication method is critical. But how do you
Top 5 API Documentation Metrics to Improve Your Efficiency
Finally done with creating comprehensive docs for your API? You’re happy with what they look like, but will actual users find them helpful and easy to navigate? There’s only one way for you to know: tracking API documentation metrics. This article dives into the key API documentation metrics and explores not just what to track,
API Security Best Practices for Cloud vs. On-Premise Environments
Back in December of 2021, Twitter (or X nowadays) suffered its biggest data breach in history. One of its APIs allowed malicious actors to submit email addresses or phone numbers on the platform and get back their associated Twitter handles. With this method known as “scraping,” millions of Twitter users’ information was breached, even for anonymous
Developer Portals: A Resource-Efficient Way to Improve the UX of Your APIs
Navigating a chaotic tech ecosystem can take away a ton of time from your team. Rather than delivering results, they may be looking for information. And that’s true even for product managers. According to Stack Overflow’s 2023 survey, 49% of managers and developers spend more than 30 minutes a day answering questions. All of these
Microservices vs API
The terms API and microservices are often thrown around pretty loosely. What do these terms actually mean? How do they relate to one another? In this piece, we’ll tackle these questions, as well as answer some common misconceptions in the space. What is an API? Before we discuss microservices, we should first define what an
API First Approach: Why Leading Tech Teams Prefer It
Traditional development can often feel like building a house of cards, one wrong move and the whole thing comes crashing down. We’ve all been there: struggling to get siloed teams working together, legacy systems that creak like rusty hinges, and applications that collapse under pressure like a flimsy pop-up tent. But what if there
The Top 10 API Metrics to Demonstrate Performance and Drive Improvement
Monitoring API performance can often feel like walking in the dark. You may have created a robust API, but without proper insights, you can’t fully understand its performance and potential shortcomings. And you’re not alone. Many teams struggle with tracking the right API metrics because narrowing things down to the most relevant KPIs is challenging.
API Workflow Automation with Josue Negron
From high school entrepreneur to his current position, Josue Negron has been working in tech for most of his life. As a Senior Principal Product Solutions Architect in the R&D organization at OneTrust, his first priority after being hired was to improve their API documentation and developer experience. Today, he’s something of a product manager
API Documentation Essentials: From Creation to Integration
Welcome to the often chaotic realm of API documentation. A place where developers pray for solid examples instead of placeholder syntax. Technical writers try to balance technical accuracy with user-friendly language. Tech leads become masters of version control, and product managers…well, they manage the storm of feature requests and shifting priorities. If you work in
How to Write API Documentation Everyone Can Read
Starting your API documentation can be a daunting task. Whether you’re learning the ropes for the first time, looking for a refresher course, or want to improve your existing docs, we’re here to share our best practices and tips for writing it, along with the pitfalls to avoid. Let’s get started 💪 The goal of
4 Steps to Implementing Stellar Documentation
As a minimalist, I’m rarely excited to purchase things, yet I can’t help but share how awesome this KeShi foam roller kit is. Interestingly, the magical part isn’t the foam roller or the massage stick or the spiky ball you step on to cause infinite pain and gain… The best part is that little booklet,
7 Crucial Design Elements for Your API Documentation
User interface and experience (UI/UX) are a crucial part of professional, in-depth API documentation. Think of your documentation as the UI/UX of your API, badly-designed or difficult to use documentation can do a lot to dull the shine of an amazing API. A great developer experience means giving your users access what they want
Get To Know Your User for a Better API
APIs are hard to use, but they don’t need to be that way. At ReadMe, we help companies to make their APIs easier to use through documentation. Most of these companies make a product and build an API on the side (“product” companies vs. “API-only“ companies). Since the API is an addition to the product,
How to Engage Your API Users (and Get More of Them)
What’s the point of building an API if nobody uses it? In the API world, the saying “If you build it they will come,” absolutely doesn’t hold true. As a matter a fact, if you build an API without marketing, explaining, and documenting it well, you’re on your way to getting lots of people to
The Rise of API-First Companies
If you told developers back in 2005 that they could make money off of an API, they’d laugh at you. The notion that you can build just a layer of software, just one functionality, and sell it as a product seemed insane. The obvious problem with “selling” an API as a product is
The History of REST APIs
In 1999, the API environment was a free-for-all. At that point, most developers had to deal with SOAP (Simple Object Access Protocol) to integrate APIs. And the “simple” part of that acronym is not to be taken literally. To make a call, they had to hand-write an XML document with an RPC call in the
What is Swagger and Why Does it Matter?
In the early 1800s, the American railroad was a free-for-all. Every city had its own time calculation, which meant that there were over 300 different time zones across the country. This made train schedules incredibly difficult to coordinate and long trips nearly impossible to plan. At a time when trains were a popular method of
Why These API Docs are Better Than Yours (And What You Can Do About it)
Once upon a time, API docs were written as an afterthought. Developers would build a new platform and then pour all their efforts into designing an API that would give other developers access to their product. Then, they would haphazardly hack together a list of endpoints and params and call it a day. But the
Why You Should Let Robots Help You Write Your API Documentation
Creating clear, beautiful documentation is one of the biggest pains of being a developer. That’s why autodoc tools like Rdoc are so appealing. Type a line in your terminal, and like magic, you get an HTML file filled with your API specs. The problem is that the results end up looking like this: # Generic
What is API Documentation (and Do You Really Need It?)
Ever tried to put together a complex piece of furniture without the instructions? We all know that’s typically a recipe for disaster. But that’s exactly what some companies expect developers to do, when they have API documentation that’s hard to find, poorly maintained, or difficult to understand…or worse yet, don’t have any API documentation at
DriveWealth’s Justin Jenkins on DX & Improving Your Docs
At ReadMe, we think a lot about creating a great experience for the developers that are building with our customers’ APIs. But we care a lot about the folks responsible for those APIs, too! Behind the scenes of every developer hub, there’s a team of engineers, product managers, and technical writers who make the magic
Technical Writing for APIs: Q&A with Beth Favini, Director of Product Documentation at Couchbase
At ReadMe, we think a lot about creating a great experience for developers building with our customers’ APIs. But we care a lot about the folks responsible for those APIs, too! Behind the scenes of every developer hub, there’s a team of engineers, product managers, and technical writers who make the magic happen ✨ Today,
6 Faux Pas of HTTP API Design
HTTP APIs are very loose by definition: there’s no standards body, no API validator and not always someone there to tell you when you may be doing something incorrect. At ReadMe we have lots of experience in building, consuming and viewing APIs created by others. We even have our own open source API Explorer which
5 Types of API Documentation for a Successful API
Close your eyes and picture API documentation. You probably imagined a reference guide, that three column page that lists all the endpoints, and then enumerates all the params and options for each one. There are many different ways to document your API, however, and you’ll need them all to have a successful API. The
The Ultimate API Documentation Checklist
Your API is only as good as its documentation. If you’re on this page, you likely already know the value of having thorough, clean, and navigable documentation, that’s easy for users to understand and take action on. It’s the only thing that’s standing between your API and all the developers who are trying to build
7 Best Practices for Writing and Updating API Docs
Developers respect clean, simple code. We have to be experts at finding ways to do more with less. And while that skill set is highly valued in development, it doesn’t always transfer over to writing great documentation. API documentation has to be more than the bare necessities of methods and endpoints. It needs examples, summaries,
Developer Experience
Four Ways to Make Your API More Enjoyable to Use
At ReadMe, we love APIs, and we love them even more when they get whimsical, so much so that it’s part of our company’s mission. The problem with APIs, however, is that they can often be business up front without the party in the back. How can we make APIs fun? Let’s look at some unique
7 Unconventional Opportunities to Improve Your API Documentation
When developers think of documentation, we often tend to think of walls of texts or verbose reference guides. However, the purpose of documentation is to be the UI layer for an API or code library: when you’re learning something new, documentation is the frontend that you spend most of your time interacting with. At ReadMe,
Adding Clarity and a Dash of Whimsy to API Error Messages
I happened upon an error onceAnd it was drab and dire!Instead of bringing sadnessWhat if errors could inspire? Off to vim, I rushed to writeThe PR was merged in no time.Now every time you get a warningIt’s paired with a cute rhyme! We completely redid our error messages, adding more than just a bit of
How to Do Developer Marketing That Doesn’t Suck
Today we’ve got a special guest on the blog, Ceci Stallsmith! If you were at API Mixtape 2023, you got to see her in action as a speaker. If you missed her talk, you’re in luck, because today’s post is covering the same topic: how to create developer marketing that doesn’t suck. Take it
Helping Your Users Write Succinct API Calls With “api” ✍️
When it comes to developer experience (DX) at ReadMe, two mantras often come to mind: With these in mind, we’re always looking for new ways to make APIs more accessible and lower the on-ramp to getting started. Today, we’re sharing more about api, our open-source SDK generator. api takes your OpenAPI definition and generates a
Why DX Matters: Driving API Success with a User-First Approach
When it comes to creating and maintaining a thriving developer community for your API, developer experience is the foundation you’ll be building on. With thousands of APIs to choose from, the well-documented API that makes it easier for developers to get up and running has a competitive edge. But what exactly constitutes developer experience? Why
Hubs We Love ❤️ Little Details With a Big DX Impact
We’re big believers in “big little details” as a way to make the compass spin, so today we’re highlighting a few customers that bring that extra special attention to their hubs. API documentation is so much more than putting together your API reference, writing a few guides, and calling it a day. Your docs are
How to Write API Errors That Keep Your Users Moving Forward
The secret to good DX is doing the right thing when things go wrong. Most error messages are a dead end, telling what went wrong but offering no help. The best error messages feel more like guardrails, gently guiding the developer back onto the path and keeping things moving forward. This guide will focus mostly
How to Generate an OpenAPI Description for an API
Describing an API according to the OpenAPI Specification comes with a wide variety of benefits for maintaining APIs in production, and keeping docs automatically synchronized with your live API. You don’t have to start over-designing your API in order to adopt the OpenAPI standard! If you already have an API designed and in production, you
How to Use OpenAPI and Swagger for Documentation
Excellent API documentation experiences stem from proper use of an OpenAPI or Swagger API description file. In this guide, we explain Swagger and OpenAPI, how to create an OpenAPI or Swagger description for an API, and how to use the OpenAPI Specification to yield documentation that’s continuously up-to-date and automated! HTTP API descriptions, like those
Documenting Your API Right in Your Code With OpenAPI
OpenAPI Specification (OAS), formerly known as Swagger, has become the de facto standard for documenting APIs. While building out our support for it, however, we found it was a bit tough to create, manage, and host OAS files. There are a few tools for this out there, like Apiary or Swagger Hub. However, these are
The Most Effective API Quick Start Guides, in 7 Examples
Developers are notorious for always taking the “learn-by-doing” approach to learning. We often skim the API docs to get the basics, and then turn to our command line to start tinkering around with the code, with a bit of help from Google and Stack Overflow, of course. Turns out though, that learning-by-doing is the most effective
ReadMe 101
Best Practices: How to Get the Most From ReadMe
To help you jumpstart your ReadMe project, we’ve put together some best practices for building and maintaining a top-notch developer hub. While these are suggestions based on our team’s experience building and using ReadMe, your hub should be tailored to your specific audience since you know what they need better than anyone. Let’s dive in!
Use Cases: How to Make ReadMe Work for You
APIs come in all shapes and sizes and while ReadMe is a great documentation solution for whatever kind of API you have, we’ve created this page to help you get the most out of the right features depending on your API’s use case. ✨ Read on for: For API-first companies… Your API is the foundation of
Using My Developers to Understand API Usage and Debug Issues
After setting up Developer Dashboard, you’ll notice that there’s a new My Developers page in your dashboard. This area gives your team in-depth developer profiles and API usage analytics. Here, your team can dig into API usage, quickly debug issues, track performance, and share aggregate findings and learnings with key stakeholders. You can filter by
Customize Your DX With Developer Dashboard
When considering what makes a great developer experience, we usually break it down into the three stages of your developer lifecycle: Supporting this full developer lifecycle, from the first call through long-term integration, is what we aim to do here at ReadMe. Creating a great experience for your API users is no different
