# ReadMe > ReadMe helps teams build beautiful, interactive, personalized API documentation that developers (and AI agents) love. Every page on this site is also available as Markdown: request it with an `Accept: text/markdown` header or append `.md` to the URL. ## Pages - [ReadMe](https://readme.com/): Interactive API documentation that helps developers succeed with your API. - [About ReadMe](https://readme.com/about): The team and story behind ReadMe. - [ReadMe for AI](https://readme.com/ai): Make your API and docs work seamlessly with AI agents and LLMs. - [AI-Ready Documentation](https://readme.com/ai-ready-documentation): Documentation built to be consumed by AI agents and LLMs. - [API Documentation Template](https://readme.com/api-documentation): A template for great API documentation. - [ReadMe Blog](https://readme.com/blog): Product news, guides, and field notes on API documentation, developer experience, and docs for AI from the ReadMe team. - [Customers](https://readme.com/customers): How teams use ReadMe to build better developer experiences. - [Book a Demo](https://readme.com/demo): See ReadMe in action with a personalized walkthrough. - [API Documentation](https://readme.com/documentation): Beautiful, interactive documentation for your API. - [ReadMe Enterprise](https://readme.com/enterprise): Security, scale, and support for large teams. - [Help Center Template](https://readme.com/help-center): A template for a customer help center. - [ReadMe vs. Postman](https://readme.com/postman): How ReadMe compares to Postman for API documentation. - [Pricing](https://readme.com/pricing): Plans and pricing for teams of every size. - [Privacy Policy](https://readme.com/privacy): How ReadMe handles your data. - [Resources](https://readme.com/resources): Guides and best practices for API docs, developer experience, and AI. - [Professional Services](https://readme.com/services): Expert help migrating to and getting the most out of ReadMe. - [ReadMe for Startups](https://readme.com/startup): ReadMe pricing and perks for early-stage startups. - [Technical Documentation Template](https://readme.com/technical-documentation): A template for technical product documentation. - [Terms of Service](https://readme.com/tos): ReadMe's terms of service. - [Our Values](https://readme.com/values): What we care about at ReadMe. ## Blog - [ReadMe vs. GitBook: Which is the Best API Documentation Tool in 2026?](https://readme.com/blog/readme-vs-gitbook): GitBook shows what happened in your docs. ReadMe connects that to what happened in your API. Here's how the two compare on API testing, design control, AI discoverability, and pricing in 2026. - [ReadMe vs Mintlify: How Teams Choose an API Documentation Platform in 2026](https://readme.com/blog/readme-vs-mintlify): How ReadMe and Mintlify actually compare in 2026: who can edit docs without a pull request, what happens after an API request runs, and what AI costs on each plan. - [AGENTS.md for AI Coding Assistants: Best Practices for API Docs](https://readme.com/blog/agents-md): Learn how to write AGENTS.md files that guide AI coding assistants, cut hallucinated endpoints, reduce token usage, and keep your API docs in sync. - [What Is CLAUDE.md? A Guide for API Documentation Teams](https://readme.com/blog/what-is-claude-md): Learn what a CLAUDE.md file is, why API documentation teams should use one, and how to create, maintain, and use it with AI-ready developer documentation. - [What is an MCP Server? How to Connect One to Your Docs](https://readme.com/blog/what-is-an-mcp-server): An MCP server lets an AI agent discover, read, and call your API directly. Here's how MCP works and how to connect one to your docs with ReadMe. - [Just Enough AI, Part 1: AI for Search and Discoverability](https://readme.com/blog/just-enough-ai-part-1): This is the first in a three-part series on ways technical writers can use AI as an assistant, not as a boss. This post is about using AI to help users and LLMs find things in your documentation. - [5 Great Technical Documentation Examples (And What You Can Learn From Them)](https://readme.com/blog/technical-documentation-examples): These technical API documentation examples are detailed, well-organized, and interactive, helping you spend less time handling support requests. - [API Versioning: 7 Best Practices to Keep Your Docs Accurate Across Every Version](https://readme.com/blog/api-versioning-best-practices): Learn seven API versioning best practices to prevent breaking changes, reduce documentation debt, and keep every version of your developer docs in sync with your code. - [Best Practices for API Documentation: How to Write, Maintain, and Scale Your Docs](https://readme.com/blog/best-practices-for-creating-api-documentation): Learn the API documentation best practices that help developer teams write clearer reference content, keep docs in sync with their codebase, and scale quality as their API grows. - [Committing to Git](https://readme.com/blog/committing-to-git): History, branching, and merging kept compounding complexity on top of Mongo. Now every save is a real Git commit, with true two-way sync to GitHub, GitLab, and Bitbucket. - [How to Structure and Optimize Your Documentation for AI Visibility](https://readme.com/blog/ai-visibility-api-docs): AI visibility helps AI tools surface accurate API guidance from your docs. Find out how to structure pages, add context, and maintain AI-ready documentation. - [Announcing Shareable Branches](https://readme.com/blog/shareable-branches): Every branch now has a shareable URL, so you can get feedback from anyone on your team — no ReadMe login required. - [Redesigned Audit Logs](https://readme.com/blog/audit-logs): Updated search features, persistent URLs, and CSV export make it easier than ever to keep track of changes across every project in your Enterprise organization. - [Keep Your Docs Consistent With the AI Linter](https://readme.com/blog/linter-style-guide): How to use ReadMe's AI Linter as a style guide enforcer, with tips for writing rules and prompts that actually work. - [How to Get Your API Documentation LLM-Ready (+ Checklist)](https://readme.com/blog/llm-ready-api-documentation): A practical breakdown of what LLM-ready API documentation looks like, plus a checklist to audit your current setup. - [Migrating Enterprise Documentation to ReadMe](https://readme.com/blog/enterprise-documentation-migration): Enterprise docs migrations fail on structure, not content transfer. Learn how to approach your migration strategically and get your docs into ReadMe the right way. - [What is API Documentation (And How to Write it Well)](https://readme.com/blog/what-is-api-documentation): API documentation is everything a developer needs to build with your API. Learn what it includes, how it differs from specs and definitions, and how to write it well. - [Reviews and Notifications for Enterprise Branching](https://readme.com/blog/branching-reviews): Branching gave your team a way to edit docs without pushing straight to production. Now reviews and notifications complete the workflow, so you know what's changed, who reviewed it, and when it went live. - [Introducing GitHub AI Writer](https://readme.com/blog/ai-writer): ReadMe's AI Writer watches your codebase, detects changes that affect your docs, and creates a branch with proposed updates. Now, you can stop chasing code changes and start reviewing drafts. - [The ReadMe CLI Tool](https://readme.com/blog/cli): We rebuilt our CLI tool from the ground up. It's great for writing docs without leaving your terminal, for both humans and AI. - [A New ReadMe, Built to Work with AI](https://readme.com/blog/may-launch): We're rolling out a new ReadMe, redesigned for writers looking to work more effectively with AI to create documentation that helps developers build with agents. - [Introducing MDX-ish](https://readme.com/blog/mdxish): We built a new rendering engine for ReadMe, which combines the permissiveness of Markdown with the power of MDX! - [Give AI Agents Direct Access to Your API with ReadMe's MCP Server](https://readme.com/blog/api-documentation-mcp-server-readme): Automatically generate an MCP server from your API docs with ReadMe, and give agents the ability to search, understand, and execute your APIs directly from the tools developers already use. - [Improve Documentation Quality at Scale with ReadMe's Docs Audit](https://readme.com/blog/improve-documentation-docs-audit): Docs Audit helps teams identify gaps, enforce standards, and improve API documentation without manual reviews. - [Find & Fix API Documentation Errors with ReadMe's AI Linter](https://readme.com/blog/find-and-fix-api-documentation-errors-with-readme-ai-linter): Define your own style guide, flag errors, and fix issues with an AI writing assistant. - [Team Up with AI to Build Docs](https://readme.com/blog/team-up-with-ai-to-build-docs): ReadMe's AI launch includes a writing assistant, a built-in linter, a docs audit, and a new search experience. - [Use ReadMe’s AI Tools to Write Great Documentation](https://readme.com/blog/ai-tools-for-api-documentation): Learn how to use ReadMe’s AI tool to write, review, and improve your API docs. - [Interactive API Documentation: How to Use Custom Components in ReadMe](https://readme.com/blog/component-marketplace): Learn how to add interactive React components into your docs. - [Review & Approve API Documentation Changes with Branch Reviews](https://readme.com/blog/branch-reviews): See changes, review updates, and approve edits before your API docs go live. - [Ship Docs Like Features with Branching](https://readme.com/blog/branches): Edit, preview, and publish branches in ReadMe for full version control of your docs no matter where you work. - [Where Docs-as-Code Goes Next](https://readme.com/blog/docs-as-code): Bringing Git to ReadMe so that you can commit to the best of both worlds. - [From IDE to AI: How ReadMe bridges APIs to LLMs with MCP](https://readme.com/blog/mcp-servers): What ReadMe's support for MCP means for developers and how to edit docs right from your IDE. - [AI Meets API Docs: The Why Behind /llms.txt](https://readme.com/blog/ai-meets-api-docs): LLMs are changing how people learn about APIs. Now your docs will remain central to the experience. ## Resources - [What "LLM-Ready" Actually Asks of Your Team](https://readme.com/resources/what-llm-ready-asks-of-your-team): Making your docs LLM-ready sounds like a project. It's closer to a habit, and that's the harder part. - [Why More Context Can Make an AI Doc Agent Worse](https://readme.com/resources/more-context-worse-agent): The instinct is to give the agent everything. The better drafts come from giving it the right thing. - [Teaching an AI Agent Your Page Templates, Not Just Your Words](https://readme.com/resources/teaching-an-agent-your-templates): A style guide tells an agent how to write a sentence. It says nothing about how your pages are shaped. That second thing is where drafts go wrong. - [What to Do When the AI Agent Drafts the Wrong Thing](https://readme.com/resources/when-the-agent-drafts-wrong): A wrong draft isn't a failure of the system. It's the moment the system is supposed to catch. - [Writing Answers a Model Will Quote Word-for-Word](https://readme.com/resources/answers-a-model-will-quote): A model doesn't quote your page. It quotes one sentence from it. Write that sentence on purpose. - [How to Review AI-Drafted Doc Changes Without Rubber-Stamping](https://readme.com/resources/reviewing-ai-drafted-doc-changes): An AI writer opening branches for you is only half the workflow. The other half is reviewing the draft like you mean it. - [When to Let the AI Agent Draft, and When to Write It Yourself](https://readme.com/resources/when-to-let-the-agent-draft): An AI agent is great at mechanical work and bad at strategy. Knowing the difference is the skill that makes it useful. - [Measuring Whether Your AI Documentation Workflow Is Actually Working](https://readme.com/resources/measuring-ai-doc-workflow): The count of AI-generated drafts isn't the metric. Time-to-merge, miss rate, and support deflection are. - [Using an AI Agent to Add Interactive Components to Docs](https://readme.com/resources/ai-agent-interactive-components): Interactive components only help if you remember to use them. An AI agent that knows your component library can do the remembering for you. - [Connecting an AI Writer to Your Spec, Not Just Your Code](https://readme.com/resources/ai-writer-meets-openapi-spec): A diff-only AI writer sees what changed. A spec-aware writer also knows what the change means. The difference is whether the drafts are correct. - [What Makes a Doc Page Cite-Able by an AI Engine](https://readme.com/resources/cite-able-doc-pages-for-ai-engines): When ChatGPT or Perplexity answers a question, it picks one page to cite. Here's what makes that page yours. - [Prompting Patterns That Work with a Docs-Grounded AI Agent](https://readme.com/resources/prompting-patterns-docs-agent): A grounded agent rewards specific prompts. Here are the patterns that consistently produce drafts you can ship. - [When an AI Writer Should and Shouldn't Propose a Change](https://readme.com/resources/when-ai-writer-should-propose): A well-tuned AI writer stays quiet on most PRs. The signal is in the restraint. - [How an AI Agent Uses Your Existing Docs as Context](https://readme.com/resources/ai-agent-existing-docs-as-context): Grounding an agent in the rest of your docs is what stops it from inventing endpoints and contradicting nearby pages. - [Mapping Code Changes to Documentation Impact](https://readme.com/resources/mapping-code-changes-to-doc-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](https://readme.com/resources/ai-agent-grounded-in-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. - [Building Doc Pages That Survive Being Chunked](https://readme.com/resources/doc-pages-that-survive-chunking): An AI engine rarely reads the whole page. A few patterns keep your content useful when only one section gets retrieved. - [Designing the Review Workflow for AI-Generated Documentation](https://readme.com/resources/ai-writer-review-workflow): 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](https://readme.com/resources/ai-agent-rewriting-docs-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](https://readme.com/resources/giving-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](https://readme.com/resources/ai-writer-detecting-doc-drift): 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](https://readme.com/resources/replay-tickets-against-docs): A retrospective evaluation that replays resolved tickets against the current docs and reports what would have been self-serve. - [Schema.org Markup for API Docs in the Age of AI](https://readme.com/resources/schema-org-for-api-docs): 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. - [Common Documentation Patterns That Cause Agents to Fail on an API](https://readme.com/resources/agent-failure-patterns): A short catalog of doc patterns that work for humans but break agents, with a fix for each. - [How llms.txt Works, and What to Put in One for an API](https://readme.com/resources/llms-txt-for-apis): A short field guide to writing an llms.txt for a developer-facing product, plus a sample. - [Turning Support Tickets into Documentation Updates with an LLM in the Loop](https://readme.com/resources/tickets-to-doc-updates): A simple workflow that turns resolved tickets into draft doc updates, without taking humans out of the loop. - [What GEO and AEO Mean for Developer Documentation](https://readme.com/resources/what-geo-aeo-means): 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](https://readme.com/resources/optimizing-for-chatgpt-claude-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. - [What LLMs Tend to Hallucinate When API Docs Are Incomplete](https://readme.com/resources/llm-api-hallucinations): A checklist of the most common invented details, useful when reviewing a reference for gaps. - [How Agents Pick Which Version of Your Docs to Read, and How to Influence It](https://readme.com/resources/doc-versions-and-agents): Stale doc versions reach agents through training data, search caches, and version routing. Each has a different way to push them toward current docs. - [How Stale Documentation Affects Token Usage and Agent Behavior](https://readme.com/resources/stale-docs-token-cost): 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](https://readme.com/resources/api-docs-eval-set): 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. - [Writing Documentation That Works for Both Humans and Language Models](https://readme.com/resources/writing-for-humans-and-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. - [MDX Cheat Sheet and Quick Reference Guide](https://readme.com/resources/mdx-cheat-sheet): 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?](https://readme.com/resources/mdx-vs-markdown): 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](https://readme.com/resources/api-design): 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](https://readme.com/resources/automated-api-documentation): 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](https://readme.com/resources/bidirectional-sync): 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](https://readme.com/resources/adaptive-api-documentation): 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](https://readme.com/resources/helpful-api-error-messages): 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](https://readme.com/resources/how-to-create-interactive-api-documentation): 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](https://readme.com/resources/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](https://readme.com/resources/an-example-filled-guide-to-swagger-3-2): 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](https://readme.com/resources/api-workflow-automations-with-josue-negron): 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](https://readme.com/resources/basic-oas-server-variables-support): Update (Feb 18th, 2022): We’ve since shipped support for enums and you can now manually enter Server Variables via . 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 - [Combining API Metrics with API Error Docs](https://readme.com/resources/combining-api-metrics-with-api-errors): 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: - [Challenge Coins and Company Credits](https://readme.com/resources/developing-company-culture-as-a-startup): Startups are a team sport. Some people are recognized with salaries or equity, however much of the help we’ve gotten along the way has been less formal. Our team may be small, but the “ReadMe family” is much larger. When I heard about Challenge Coins, I knew we’d found a way to include and recognize everyone - [Documenting Microservices in ReadMe](https://readme.com/resources/documenting-microservices): 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?](https://readme.com/resources/enterprise-api-docs-whats-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](https://readme.com/resources/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](https://readme.com/resources/generating-a-swagger-file-from-your-code-2): 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](https://readme.com/resources/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 - [How we did our first Net Promoter Score, and why you should too!](https://readme.com/resources/how-we-did-our-first-net-promoter-score-and-why-you-should-too): We recently completed our first Net Promoter Score (NPS). It’s something we’ve all seen before, a simple email or pop-up that asks “On a scale of 0-10, how likely are you to recommend this product to a friend or colleague?”, then “why?” in some form. We’d been considering doing an NPS for a couple months, - [I Hated Writing Documentation so I Founded a Company](https://readme.com/resources/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](https://readme.com/resources/jamstack-static-sites-dynamic-apis-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](https://readme.com/resources/making-better-use-of-herokus-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](https://readme.com/resources/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](https://readme.com/resources/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](https://readme.com/resources/readme-flavored-markdown): 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](https://readme.com/resources/the-best-rest-api-template-2): 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](https://readme.com/resources/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 !), 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](https://readme.com/resources/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](https://readme.com/resources/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](https://readme.com/resources/api-specification): 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?](https://readme.com/resources/graphql-vs-rest): 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?](https://readme.com/resources/sdk-vs-api): 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🛡️](https://readme.com/resources/api-authentication): 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](https://readme.com/resources/api-documentation-metrics): 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](https://readme.com/resources/api-security-best-practices): 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](https://readme.com/resources/developer-portals): 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](https://readme.com/resources/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](https://readme.com/resources/api-first-approach): 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](https://readme.com/resources/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](https://readme.com/resources/api-workflow-automation): 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](https://readme.com/resources/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 - [Best Practices: How to Get the Most From ReadMe](https://readme.com/resources/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](https://readme.com/resources/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 - [How to Write API Documentation Everyone Can Read](https://readme.com/resources/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 - [Using My Developers to Understand API Usage and Debug Issues](https://readme.com/resources/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 - [4 Steps to Implementing Stellar Documentation](https://readme.com/resources/4-key-questions): 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](https://readme.com/resources/7-ways-to-improve-the-design-of-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 - [We’re an AWS Partner🎉Meet the Developer Hub for Amazon API Gateway](https://readme.com/resources/announcing-our-amazon-partnership-developer-hubs-for-amazon-api-gateway): In the modern API landscape, developers expect more than just an API reference when getting started with an API. Providing comprehensive guides, tutorials, and up-to-date code samples can be the difference between a user choosing your solution, or going with a competitor. But building and maintaining a developer hub is costly for engineering and - [Auto-Magically Sync to ReadMe With GitHub Actions 🎩](https://readme.com/resources/auto-magically-sync-to-readme-with-github-actions): In the above example, the following takes place: An OpenAPI definition is located and validated using rdme openapi:validate ✅ The CLI detects that the working directory is a GitHub repository 🕵️ … and a few key-presses later, we’ve created a GitHub Actions workflow file! ✨ Once the workflow file is pushed to GitHub, the validation - [Cookin’ Up Code Samples With ReadMe Recipes](https://readme.com/resources/cookin-up-code-samples-with-readme-recipes): Getting started with a new API can be complicated. But we don’t think it has to be! So much time goes into making product onboarding smooth and simple, shouldn’t APIs be the same way? That’s why we built ReadMe Recipes. They’re a new way to highlight your top API use cases and walk through - [Customize Your DX With Developer Dashboard](https://readme.com/resources/customize-dx-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 - [How Developer Metrics Boost Your Business](https://readme.com/resources/developer-metrics-can-boost-your-business): The work of building a great developer experience is never done. Your API can change, your audience can change, and your goals can change. Features are deprecated and there are always ways to improve the experience. But how do you measure the impact of your changes and prioritize what changes to make next? Use analytics - [Get To Know Your User for a Better API](https://readme.com/resources/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)](https://readme.com/resources/how-to-engage-your-api-users): 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 - [Four Ways to Make Your API More Enjoyable to Use](https://readme.com/resources/how-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 - [Lights ⚡, Camera 🎥, GitHub Actions! ✨](https://readme.com/resources/lights-camera-github-actions): Here at ReadMe (and for most companies with engineering teams), GitHub is something of a household name. It’s an essential part of our workflow for managing code. We do our code reviews, code releases, and even many aspects of our documentation process all within GitHub. While the ReadMe dashboard was designed for teams to manage - [​​New and Improved Suggested Edits​​](https://readme.com/resources/new-improved-suggested-edits): Have you ever suggested an edit to a page, only for your submission to go into a bottomless void with no idea if the administrators actually used it?​​ ​​Well fear no more! With the latest and greatest improvements to Suggested Edits on ReadMe, it’s easier than ever to view and track the status (i.e. open, - [The Rise of API-First Companies](https://readme.com/resources/on-the-origins-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 - [Onboarding New API Users With Personalized Docs ✨](https://readme.com/resources/onboarding-users-with-personalized-docs): Given the choice between a run-of-the-mill experience that’s the same for everyone and a personalized experience tailored just for you, which would you choose? It’s safe to say that most people would prefer the personalized experience that meets their unique needs, especially if it doesn’t come at the cost of time or resources. This is - [OpenAPI Initiative, OpenAPI v3.1 Support, Oh(penAPI) My!](https://readme.com/resources/openapi-initiative-v3-1): If you’re a longtime follower of ReadMe history, you’ll know that we’re no stranger to the OpenAPI Specification (OAS). Since our earliest days as a company, we’ve been: Writing blog posts about OAS ✍️ Our most viewed blog post is a short walkthrough of the differences between Swagger 2.x and OpenAPI 3.x! Supporting OAS as - [ReadMe Micro: Because Microservices Deserve Big Solutions](https://readme.com/resources/readme-micro-microservices-solutions): ReadMe already makes it easy to create great developer hubs for public and partner APIs. But we know that companies often have hundreds (if not thousands!) of internal APIs to track, and that tracking and documenting that many APIs can be something of a logistical nightmare 😱 That’s why we’ve created ReadMe Micro. With it, - [Quick Switcher: Speed Up Your Workflow](https://readme.com/resources/speeding-up-your-workflow): Introducing Quick Switcher, the fastest way to navigate ReadMe. How does it work? Press ⌘+K on Macs or Ctrl+K on Windows anywhere inside ReadMe to search for and jump directly to: Pages (from Guides, API Reference, Custom Pages or Changelog posts) Settings (any sidebar menu item in both Enterprise groups and regular projects) Projects (other - [The History of REST APIs](https://readme.com/resources/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 - [7 Unconventional Opportunities to Improve Your API Documentation](https://readme.com/resources/things-that-dont-seem-like-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, - [ReadMe + 1Password + 2FA =💙](https://readme.com/resources/two-factor-auth): I’m not sure that anyone at ReadMe expected (or honestly even wanted) my love for 1Password to spill into our company blog … but here we are! I’ve always admired 1Password’s ability to blend great user experience with robust security (generally considered to be opposites). Its built-in two-factor authenticator is an excellent example of this, it - [What is Swagger and Why Does it Matter?](https://readme.com/resources/what-is-swagger-and-why-it-matters): 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 - [Adding Clarity and a Dash of Whimsy to API Error Messages](https://readme.com/resources/whimsical-errors): 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 - [Why These API Docs are Better Than Yours (And What You Can Do About it)](https://readme.com/resources/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](https://readme.com/resources/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 - [Workflow: Collaborative Documentation with Suggested Edits](https://readme.com/resources/workflow-collaborative-documentation-with-suggested-edits): Recently, we released a brand new version of our Suggested Edits feature and as we were testing it internally, it dramatically changed how we approached writing documentation. It’s allowed us to more easily collaborate on documentation and merge updates exactly when features go live. For all major changes to documentation (whether it be new features, - [How to Do Developer Marketing That Doesn’t Suck](https://readme.com/resources/how-to-do-developer-marketing-that-doesnt-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 - [DriveWealth’s Justin Jenkins on DX & Improving Your Docs](https://readme.com/resources/drivewealths-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 - [Authenticating Into ReadMe’s CLI With 1Password and Your Fingerprint ☝️](https://readme.com/resources/1password-shell-plugin): Long-time followers of the ReadMe blog know I have been absolutely shameless in my love for 1Password. It’s a great password manager that we use here at ReadMe to securely store shared logins, API keys, and more. Staying secure online is increasingly difficult these days, and we’ve been able to safely rely on 1Password for - [Helping Your Users Write Succinct API Calls With “api” ✍️](https://readme.com/resources/helping-your-users-write-simpler-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 - [Technical Writing for APIs: Q&A with Beth Favini, Director of Product Documentation at Couchbase](https://readme.com/resources/technical-writing-apis-q-a-with-beth-favini): 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, - [Why DX Matters: Driving API Success with a User-First Approach](https://readme.com/resources/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](https://readme.com/resources/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](https://readme.com/resources/how-to-write-good-api-errors): 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](https://readme.com/resources/how-to-generate-openapi-descriptions): 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](https://readme.com/resources/how-to-use-openapi-and-swagger-spec-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 - [6 Faux Pas of HTTP API Design](https://readme.com/resources/http-api-faux-pas): 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](https://readme.com/resources/types-of-documentation): 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 - [Documenting Your API Right in Your Code With OpenAPI](https://readme.com/resources/documenting-your-api-in-your-code-with-swagger): 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](https://readme.com/resources/the-most-effective-api-quickstarts-in-8-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 - [The Ultimate API Documentation Checklist](https://readme.com/resources/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](https://readme.com/resources/best-practices-for-writing-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, ## Customer stories - [Akamai: Customer Story](https://readme.com/customers/akamai) - [Atelio: Customer Story](https://readme.com/customers/atelio) - [Baremetrics: Customer Story](https://readme.com/customers/baremetrics) - [Clever: Customer Story](https://readme.com/customers/clever) - [Doppler: Customer Story](https://readme.com/customers/doppler) - [Drivewealth: Customer Story](https://readme.com/customers/drivewealth) - [Gusto: Customer Story](https://readme.com/customers/gusto) - [Heap: Customer Story](https://readme.com/customers/heap) - [Onetrust: Customer Story](https://readme.com/customers/onetrust) - [Scale: Customer Story](https://readme.com/customers/scale) - [Socure: Customer Story](https://readme.com/customers/socure)