In my last post, I introduced Troyal, a fictional API for tracking music and film royalties, and shared the product brief, the API design and the README.
And now, I just wrote the Getting Started guide.
If you're a developer trying a new API, this is the page you open first. Its primary job is to get you from nothing to a working request as fast as possible.
My guide takes you through:
- Getting an API key
- Sending your first request to
GET /works - Reading the response
- Fixing the most common errors (401, 404 and 429)
The part I paid most attention to was the troubleshooting table. Errors are when a developer needs the docs most, and a clear "here's what went wrong and what to do" prevents frustration.
Everything is public on GitHub, and Part 3 will be the OpenAPI spec.
Troyal is fictional. The documentation is real.
Top comments (6)
"Troyal is fictional. The documentation is real." That line belongs on a poster in every docs team's office. 🎬
"Troyal is fictional. The documentation is real." That line belongs on a poster in every docs team's office. 🎬
Writing full docs for an imaginary API is one of the best ways to learn this craft, because we get to play every role: the product manager, the API designer, the writer, and the developer staring at a 401 at 11pm.
A fun next step for the guide is the five-minute test. We hand it to a friend who has never seen Troyal, start a timer, sit on our hands, and write down every moment they pause. Each pause becomes a fix in the next version. Bonus points if the friend gets a 200 before the kettle boils. ☕
Looking forward to Part 3!
Writing full docs for an imaginary API is one of the best ways to learn this craft, because we get to play every role: the product manager, the API designer, the writer, and the developer staring at a 401 at 11pm.
A fun next step for the guide is the five-minute test. We hand it to a friend who has never seen Troyal, start a timer, sit on our hands, and write down every moment they pause. Each pause becomes a fix in the next version. Bonus points if the friend gets a 200 before the kettle boils. ☕
Looking forward to Part 3!
The troubleshooting table being the part you paid most attention to is the right instinct — the docs people read first get skimmed, but the docs people read at 11pm with a 401 get read word for word.
One thing I'd add: the "Getting an API key" step is where most Getting Started guides quietly lose people. If it involves waiting for an approval email or navigating a dashboard with six tabs, the guide should say that up front, so nobody assumes the API is broken when nothing works yet.
Also curious — are you writing the OpenAPI spec by hand, or generating it from the docs you already have? The two drifting apart is usually where the "official" docs and reality stop matching.
Thank you, this is really helpful. You're right about the API key step, since that's where a lot of people get lost. To answer your question, I'm writing the OpenAPI spec by hand, one endpoint at a time, and checking it in Swagger Editor. Part 3 is up now if you'd like to see it.
"Troyal is fictional. The documentation is real." That line belongs on a poster in every docs team's office. 🎬
Writing full docs for an imaginary API is one of the best ways to learn this craft, because we get to play every role: the product manager, the API designer, the writer, and the developer staring at a 401 at 11pm.
A fun next step for the guide is the five-minute test. We hand it to a friend who has never seen Troyal, start a timer, sit on our hands, and write down every moment they pause. Each pause becomes a fix in the next version. Bonus points if the friend gets a 200 before the kettle boils. ☕
Looking forward to Part 3!
Thank you, I love this. The five-minute test is a great idea. Part 3 is up now, where I turn the API design into an OpenAPI spec.
This is excellent work!🌸❤️❤️🥳🥳🥳🥳🎂🎈✨✨🩷❤️