Developer quick-start guides with Amit Jotwani
Amit Jotwani's test for whether a quick start guide is actually good: ask a stranger to follow it while you watch. He's found that people who already know the product have permanent blind spots — and that half the time, the guide is quietly asking the reader to go find their own test data first.
Amit Jotwani is the founder of HelloDX, which audits developer documentation, APIs, and quick-start guides for friction, and previously worked in developer experience at Retool and Amazon Alexa. Jack came across Amit's writing on EveryDeveloper while working on his own quick-start guide for Streampot, and brought him on to pick apart what actually makes a guide work.
We get into why a quick-start guide should follow the same discipline as writing a clean function — do exactly one thing — why the person who wrote the guide is the worst person to judge whether it's clear, and the small, easy-to-miss decisions, like providing sample data instead of asking the reader to go find their own, that quietly determine whether someone finishes the guide at all.
The Q&A below is experimental — extracted from the episode transcript with AI. If you spot a mistake, let us know at jack@scalingdevtools.com.
What actually defines a quick start guide, as opposed to any other kind of documentation?
Something very focused on getting someone from zero to one on a specific thing, with step-by-step instructions and a clear result stated up front — you should know exactly what you're getting into and what you'll get out of it before you start. A lot of guides fail this by assuming too much and expecting the reader to go do extra work themselves, which just adds friction. I think about it the same way I think about writing clean code: a function should do one thing. You can write a quick-start guide that shows twenty things at once, but it becomes hard to follow, hard to maintain, and you never get the satisfaction of checking off one simple box.
How do you find the right scope when a product genuinely does a lot, and setup is non-trivial?
Start with something close to a hello-world. Take AssemblyAI: at its core, it's a transcription API — give it an audio URL, get a transcript back. That's the first guide: step by step, taking a URL and transcribing it in, say, Python. New jargon should only get introduced as it's actually needed, not all up front. Once that's solid, you can add a second guide that builds on it — say, speaker recognition — that explicitly links back to the first one rather than repeating it. Each individual guide should still be describable in one sentence; if you need two or three sentences to explain what a guide does, it's doing too much, the same way a function that needs a paragraph to explain probably needs splitting up.
What's the difference between a bad introduction and a good one?
A bad one starts with something like 'Welcome to my guide' — nobody cares about being welcomed. What people actually want to know immediately is what they'll get out of it, which specific APIs or endpoints they'll touch, and what they'll be able to do by the end. That doesn't need to be long — if anything, shorter is better, because it comes down to respecting a developer's time. I'll say something a little controversial: these guides should be written by the developers actually writing the code for them, not overwritten by people optimizing for SEO or pageviews, because the moment you dilute that value, developers see through it immediately.
What's an example of a guide trying to do too much at once?
Jack shared a guide he'd written for building an AI video editor that required Docker, an S3 bucket, and Cloudflare setup before you even got to the actual product being demonstrated. Looking through the prerequisites, my instinct was to ask which of these are actually optional — could you just use a file sitting locally on your machine as the very first step instead of setting up an S3 bucket? You can always add cloud storage as a later version once someone's gotten the basic thing working; that doesn't have to be the zero-point-one. The core discipline is the same as how I write my own guides: get the roughest possible first version working, even if the code is a little messy and not properly modularized yet, and only add complexity in layers after that.
Should best practices — like putting API keys in a .env file instead of hardcoding them — make it into a quick-start guide?
That's a genuine judgment call with no clean right answer. You obviously want to encourage good practice, but every best-practice aside adds a bit of complexity that's arguably outside the scope of what the tutorial is actually trying to teach. You have to be intentional about which trade-off you're making and stay consistent with what you're actually trying to achieve for that specific guide, rather than reflexively including every best practice everywhere.
Why is it so hard for the person who wrote a guide to judge whether it's actually good?
People who are familiar with a product have blind spots and biases they can't see past — they don't notice the things a fresh pair of eyes would immediately trip over. That's the whole premise behind friction logging: get someone technical enough to follow along, but unfamiliar with the specific product, and watch exactly where they get stuck. One recurring example: if your API needs some kind of input asset — a logo, an audio file, whatever — and your guide doesn't provide one, you're making the reader do extra work they probably won't bother doing, unless they have some outside incentive to push through. Providing good sample data is actually in the API's own interest too, because you control exactly what shape of data demonstrates the product well, rather than leaving someone to grab a random file that happens to be sitting on their computer.
What are the small details that separate documentation that really gets adoption right?
Resend and Supabase both do this well: when you're logged in, the sample code in their docs already includes your own API key, so there's nothing to swap out before you can run it. It sounds small, but it's exactly the kind of thing that reduces friction to getting started. I also think inspirational, specific use cases matter more than people assume — 'you can do transcription' is generic, but 'you can send a YouTube URL and get a transcript, then email the results using an API like Resend' gets someone's creative wheels turning about their own use case. Often it just takes one developer kicking the tires over a weekend, then going back to their team saying they hacked something together that solves a problem the team's been stuck on.
How do you actually know if a quick-start guide did its job?
It's a classic hard-to-measure problem, same as trying to gauge the value of speaking at a developer event — you can't always draw a clean line back to the outcome. Views and clicks aren't a great proxy on their own. Better signals are whether it's getting mentioned organically on social media, and for an API specifically, whether you see a real bump in usage or calls to a specific endpoint afterward. Before publishing anything, I share it with a few trusted people and gather feedback directly, because sometimes something you wrote won't seem to lead anywhere for months, and then it turns out someone read it, joined a company, and quietly drove adoption there — and you'll never be able to draw the direct line back to the guide that started it.
Links & references
This episode is brought to you by WorkOS.