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.
