Menu

Part 4: I wrote the page developers read when something breaks, and set up a Jira board to track it all.
📰

Part 4: I wrote the page developers read when something breaks, and set up a Jira board to track it all.

DEV Community: github·Joyce Foster·4 days ago
#z4s768Ov
#devtogithub#technology#devto#dev#troyal
Reading 0:00
15s threshold

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.…

Continue reading — create a free account

Join HashtagPLUS to read full articles, follow hashtags, vote, and join the conversation.