From Chaos
to Clarity

Developers are a no-bs audience — they care about getting something done fast. My docs philosophy is centered on “outcomes.”

The flow of information and every particular page should help developers achieve critical outcomes:

• Making them fall in love with your product
• Helping them achieve their tasks

Docs are as much about marketing messaging as they are about developer experience. You have to figure out how you want people to use your product, because that is how you can ensure they succeed fast, realize its value, and convert.

Before writing, you need CLARITY on what you want people to achieve with your product. And then handhold them through it.

We lacked this internal clarity at Supermemory. They have two core products: the Memory API and the Memory Router. Both overlapped and sounded similar. Both solved “memory.” Customers were confused.

I got on a call with Dhravya Shah (CEO) and asked him just one thing: For what outcome is the Memory API best, and for what outcome is the Memory Router best?

We finally locked it in:

From then on, everything reinforced that idea.

I scraped Discord messages, tweets, asked Dhravya to forward emails from customers complaining, and got on many calls with the engineers to find every bit of feedback possible.

I wrote everything down and skimmed through the docs myself. Then came one of my biggest realizations:

The first thing people see is your sidebar, and that communicates a fuck ton about how much care you've put in. Does it make sense to me in my head step-by-step, or is it all over the place?

I sat down and mapped the journey from zero to “aha.”

This process repeats for each individual product. For the Memory API, I realized a dev's first step is: “How do I add a document?” So the flow had to be: Add → Check status → Query → Iterate.

Once I saw that pattern, the rest of the structure basically wrote itself.

I made a structure doc, got approval from Dhravya, and linked every page to a concrete outcome: ingesting data, filtering, searching, etc. — in order of how devs should use the product.

I opened the OpenAPI spec and started writing every endpoint by hand. Then I'd refer to the codebase to find things that weren't covered.

Cursor and vibe-docing were a huge help. I'd ask Cursor to read the SDK definitions and OpenAPI spec and produce a first draft. Then I'd spend ~3.5 - 4 hours refining it, testing snippets, fixing explanations, and ensuring things made mental sense.

A lot of the content it generated was fluff, and a lot of the code snippets were ass, but that's alright. You still have to think.

Can't emphasize enough how important visuals are to prevent your docs from becoming walls of text.

All credit to Souptik for the visual work.