DEV Community

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

Posted on

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

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.

https://github.com/joycefoster642/Troyal-API-Docs

Top comments (3)

Collapse
 
alexcodebytes profile image
Oleksandr •

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!

Collapse
 
joycefosterr profile image
Joyce Foster •

Thank you for your input!🌸

Collapse
 
joycefosterr profile image
Joyce Foster •

Excellent work!πŸ₯ΉπŸŒΈπŸŒΈπŸŒΈβ€οΈπŸ₯³βœ¨πŸ˜­πŸŽŠπŸŽ‚πŸŽˆπŸ©·βœ¨πŸŒΈ