In my last post, I talked about how I turned my Troyal API design into an OpenAPI spec. Troyal is my fictional API for tracking music and film royalties.
And now, I have completed 3 more tasks.
Firstly, I wrote an error codes guide: When a request fails, developers need to know three things quickly; what went wrong, why, and how to fix it. My guide lists every error the API can return (400, 401, 404 and 429) with a short explanation of the cause and the fix, and it shows exactly what the error response looks like.
Secondly, I added a changelog: A changelog tells developers what changed in each version of an API, so they can see at a glance what's new. Mine lists the first release, 1.0.0, and what's planned next.
Thirdly, I set up a Jira board: I turned each piece of documentation work into a ticket, from the product brief to the OpenAPI spec. Seven are done and five are still to come. It's a small thing, but it shows how I'd plan and track docs work with a team.
Here's what I'm still building: the ownership splits and royalty statements in the spec, a webhooks guide, and a docs site.
As usual, everything is public on GitHub.
Troyal is fictional. The documentation is real.
Top comments (3)
The error code guide is the MVP here. "What went wrong, why, and how to fix it" is exactly what developers need at 2 AM when an integration fails. A lot of public APIs still just return a generic 400 with no context.
Also, setting up a Jira board is a massive green flag. It shows hiring managers that you don't just write docsβyou know how to plan, track, and manage documentation projects like an actual engineering team member. Keep it up!
Thank you for your input!πΈ
Excellent work!π₯ΉπΈπΈπΈβ€οΈπ₯³β¨πππππ©·β¨πΈ