Writing API Documentation from a UX Viewpoint

TL;DR

Why ONDA, a B2B hospitality solution, obsesses over 'good' API docs

Talk about designing API docs with UX in mind, and most people think: "But end customers never see those, right?" After all, UX usually refers to the user experience of software and services. So why does ONDA—a B2B hospitality solution—take this route?

ONDA builds innovation where opportunity exists

First, context. ONDA offers a suite of solutions—from guesthouses to hotels—that make property operations easier. The flagship? ONDA HUB, our all-in-one distribution system.

Properties sync inventory and rates with multiple sales channels—Airbnb, Agoda, you name it—in one go. We're the bridge connecting properties and OTAs. Why does this matter?

Because the property–OTA workflow is still manual in many cases. Without a channel manager, if a booking comes in on Site A, you have to manually update inventory on Site B. Miss the window, and you've got a double-booking. ONDA HUB removes that friction—tech doing the heavy lifting so properties save time and labor.

The foundation of channel management: API documentation

The distribution system splits into two streams: OTA connections and property supplier connections. Today, ONDA manages over 40,000 properties and integrates with 40+ sales channels.

My team (Product Owners—POs who plan and build the product) focuses on expanding this network: onboarding more suppliers to grow inventory, and connecting more sales channels (beyond the major Korean and global OTAs we already work with) to sell that inventory better.

And at the heart of all this? API documentation. Integration work starts with understanding the API docs.

Quick primer: what's an API?

Application Programming Interface. It's the mechanism that lets two software components talk to each other. APIs define how requests and responses are structured—and API documentation explains how to construct those requests and handle those responses. (Source: AWS)

Think of an API as a door through which companies (or departments) exchange data.

ONDA's API is simple in concept: pull property info, send it to sales channels, and push reservations back to the property. The API docs spell out how we exchange data with suppliers and sales partners.

But reading someone else's API docs isn't easy. Specs vary—what APIs exist, how they behave, what they return. Plus, docs are full of English terms and numeric codes, so first-timers often struggle.

This means a lot of time goes into explaining the docs—context, clarifications, back-and-forth Q&A. Rinse, repeat.

Reducing communication overhead: Readme + OAS

To cut communication costs and speed up integrations, documentation format matters. Write clearly, let partners test live, and you'll save their resources and prevent bugs caused by misunderstanding.

Airbnb, Upbit, Karrot—lots of companies use Readme.

We tried a bunch of tools. In the end, we landed on Readme. If you're in API design or dev, you've probably heard of it. The killer feature? Not just pretty spec rendering—partners can test right in the docs. That boosts comprehension like nothing else.

Analogy: explaining kimchi jjigae to a foreigner. You can say "spicy stew with fermented cabbage broth"—or you can hand them a spoon. Taste beats description. Same with APIs: instead of reading wall-to-wall text, let partners send requests and see responses in the doc itself.

You can test API calls directly in the documentation.

That said, adopting Readme had a learning curve. Different companies in the same vertical use slightly different terminology—so you need to document every response field (type, description, etc.). Readme's default editor didn't cut it.

Upbit (Korea's biggest crypto exchange) must've hit the same wall—they opted to write responses as prose in the doc body. But compared to Airbnb's approach, it felt clunky.

Clear tables, easy to follow. But actual response structure isn't shown—hard to grasp the full picture.

Every field's purpose, format, and example values are right there. No hunting around the doc.

The difference? Readme's default editor vs. OAS (OpenAPI Specification)—a standard for RESTful APIs.

OAS uses language-agnostic JSON and YAML to define RESTful API specs, so anyone on any platform can use it. That universality was a huge draw. (More here)

For us, developers and PMs at OTA partners and suppliers are the customers. So we approached the docs as a product—from a UX lens—and chose OAS to make response fields intuitive at a glance.

What we adopted to write better API docs

Every company documents APIs differently—and assigns different roles. At ONDA, POs own documentation. We talk to suppliers and sales partners, and we need precise specs when collaborating internally with devs.

How do non-developer POs and PMs write good API docs in OAS format?

✔️ YAML

OAS supports JSON and YAML—both language-agnostic data formats. JSON has lots of brackets and braces; it looks dense. Our team understands code well enough that either would've worked, but for the less technical, we picked YAML—human-friendly syntax.

✔️ VS Code

Tools like Swagger Editor already make OAS authoring easy. But for better collaboration and usability, we needed something more—VS Code fit the bill. A few extensions let even OAS newbies work without constant errors.

✔️ GitHub Desktop

For ongoing maintenance, collaboration is key—so we host OAS files on GitHub. Dev-savvy folks use CLI (command-line interface) via VS Code. For the rest, we use the GUI app—GitHub Desktop—so everyone can write and share intuitively.

90%+ drop in questions

ONDA's API docs—after the overhaul, communication overhead plummeted.

Since treating the API docs as a product—not just a spec sheet—we no longer spend time walking partners through them at kickoff. When questions do come in, we fold answers back into the docs so they don't repeat. Compared to before? Questions dropped by over 90%.

And internal satisfaction is higher too—we're not juggling multiple versions or re-explaining the same thing.

Sadly, some legacy partners still send API docs as PDFs. But beyond tools and templates, what matters is this: treat your partners like customers. Approach documentation from a UX lens. The better the docs, the faster the integrations. And the faster we integrate, the faster our network grows.