DEV Community: Jitendra Balla

The API docs pipeline that runs itself (week 1 recap)

Jitendra Balla — Wed, 15 Jul 2026 17:46:00 +0000

One week in. Let's connect the dots, because the tools are useful alone but the real win is chaining them.

Here's the pipeline:

You build and test an endpoint. You verify it with cURL. You run that through cURL to Markdown (https://markdown.co.in/tools/curl-to-markdown.html), or generate from your OpenAPI spec (https://markdown.co.in/tools/openapi-to-markdown.html) if you're spec-driven. You add the human layer: a plain description and a working first example. Then you keep it honest by regenerating in the same PR.

The whole point is that accuracy stops depending on memory. Your docs come from the things you actually ran. That's the difference between docs you trust and docs you tolerate.

Mindset shift for the week: documentation isn't a chore you do after the real work. It's a byproduct of doing the real work well.

Next week: conversion and migration. Moving between HTML, Markdown, and PDF without losing your weekend.

Your docs don't rot because you're lazy

Jitendra Balla — Tue, 14 Jul 2026 17:44:00 +0000

Every stale doc has the same origin story. The code changed. The docs didn't. And the reason isn't laziness. It's distance.

When docs live far from your code, updating them is a separate task with its own friction. You have to remember they exist, switch context, find the page, make the edit. Every step is a chance to just not bother.

Shrink the distance. Keep docs in the repo, and update them in the same pull request that changes the behavior.

This is where generated docs pay off twice. Since your API docs come from your cURL commands or OpenAPI spec, "updating the docs" becomes "regenerating the docs." Mechanical. Fast. Actually doable in the same PR.

One habit that beats all good intentions: add a line to your PR checklist that says "Docs regenerated and reviewed?" That single checkbox does more for doc quality than anything else.

And when docs and code change together, reviewers catch mismatches before they reach a user.

Great API docs don't lead with a parameter table

Jitendra Balla — Mon, 13 Jul 2026 17:41:00 +0000

Hot take: complete API docs are not the same as good API docs.

Everyone thinks great docs means listing every endpoint, every parameter, every response code. Sure, that's necessary. But it's not what makes docs good.

What makes them good is answering the first question a developer actually has: how do I make one successful request?

Nobody opens your docs wanting a reference manual. They want to get something working. Give them a copy-pasteable example that succeeds on the first try and you've earned their trust. Then they'll happily dig into the details.

My structure for any endpoint:

One plain sentence on what it does. Not "retrieves the resource" but "gets the details for a single order."
A working example. This is where your generated Markdown shines.
The reference details. Parameters, edge cases, errors. Dense is fine here.

Most docs get this backwards and open with a wall of parameter tables before you've seen a single working call. Flip it.

Swagger vs OpenAPI, explained in 30 seconds

Jitendra Balla — Sun, 12 Jul 2026 17:38:00 +0000

People say "Swagger" and "OpenAPI" like they're two different things. Here's the actual story.

Swagger came first. It was a spec plus tooling for describing REST APIs. It got so popular the spec was donated to a foundation and renamed OpenAPI. So today, "Swagger" sometimes means the old spec, sometimes the tools, and sometimes just OpenAPI out of habit.

The practical bit: if you have a Swagger file, it's almost certainly OpenAPI-compatible, and you can turn it into docs the same way.

Swagger to Markdown handles either: https://markdown.co.in/tools/swager-to-markdown.html

The bigger lesson from this week: if a machine-readable version of your API already exists in any form, you should almost never write docs from scratch. Generate first, polish second.

One tiny tip: pick one name, Swagger or OpenAPI, and use it consistently across your team. Saves new folks a surprising amount of confusion.

Your OpenAPI spec is already your documentation

Jitendra Balla — Sat, 11 Jul 2026 17:36:00 +0000

If your team defines APIs with an OpenAPI spec, you're closer to good docs than you think.

That spec already describes every endpoint, parameter, and response. Machines love it. Humans reading raw YAML? Not so much. And that gap is where docs die. Someone hand-writes a "readable" version that immediately drifts out of sync with the spec.

Close the gap. Feed your spec into OpenAPI to Markdown and get formatted docs out: https://markdown.co.in/tools/openapi-to-markdown.html

The best part is it kills the "two sources of truth" problem. Update the spec, regenerate the docs. They can't drift apart because one comes from the other.

Pro move: keep the generated docs in your repo next to the spec. When the spec changes in a PR, regenerate in the same PR. Reviewers see both change together, and nothing slips through.

Stop maintaining docs by hand next to a perfectly good spec. Let the spec do the work.

Stop retyping your API. Turn cURL into docs instantly.

Jitendra Balla — Fri, 10 Jul 2026 17:35:00 +0000

Here's an absurd thing I did for years.

I'd test an endpoint with a cURL command. It worked. Then, to document it, I'd open a Markdown file and retype the whole thing by hand. The method, the URL, the headers, the body, a sample response. Information I already had, typed twice, in a format I hated.

If that's you, today's a good day.

The cURL to Markdown tool takes your cURL command and turns it into clean, formatted API docs. Paste, get Markdown, done: CURL to Markdown

Why it matters: the cURL command is the thing you actually ran and verified. When your docs come straight from it, they're accurate by default. No translating from memory, which is exactly where mistakes creep in.

My flow now: test the endpoint, paste the cURL, tidy up the description, ship. Fifteen minutes of formatting became two.

Try it on the last endpoint you built. Watch the boring part disappear.

Nobody writes bad docs on purpose. It just happens.

Jitendra Balla — Thu, 09 Jul 2026 17:32:32 +0000

Every project I've worked on had bad docs at some point. Not once was it a decision.

It happens slowly. A feature ships without docs because the deadline was tight. The next one skips docs too, because last time nothing broke. Six months later someone opens the wiki and finds three pages that contradict each other and a README that still says "coming soon."

Here's the reframe that changed things for me: docs are not a writing problem. They're a systems problem. Good docs come from removing the friction that makes people skip writing, not from trying harder.

That's what this series is about. 30 days of making documentation less painful, using free tools you can start with today. No enterprise platform. No approval process. Just less busywork.

Tomorrow we start with the one that fixed my whole workflow: turning API tests into docs without retyping anything.

If your docs are held together with hope and copy-paste right now, welcome. Let's fix it.