Created a new API, great, but what do I need as documentation?

@sigmund

🔥The article was written with the idea that everytime we create a new API, we need to think on all the areas needed for a good documentation, in order to help the manager, the team and the product managers involved. It is a living document, so things could always be added or removed.

The template can be found here: https://github.com/strognoff/strognoff/wiki/New-API-Template

I will explain some of the sessions below:

👉Our Mission

This is the area where we(Usually Product Manager) put why we are delivering the API, what is the problem we are going to solve and the impact on the business, a well-defined mission can help a lot of the team to understand what is asked to deliver.

👏HLD (High-level Design)

High-level design, help us to understand the architecture of the API the team will build, usually following the C4 Model. It should include all the Systems the API will touch.

💛ADRs (Architecture Decision Records)

Good APIs are made of good decisions, however with time, these decisions can change, and it is always good to document the decisions so we can always come back in time and understand the pros and cons of what was decided.

⭐️Sequence Diagrams

If you are like me, then you will love Sequence Diagrams, explaining a flow to someone is hard, and for people that are trying to understand, even harder, so good sequence diagrams help to digest better the flow and nothing better than showing a picture :-).

🤯Acronyms

Every single company I worked for so far had its own acronyms, it is great to understand them and create a table explaining what they mean, so the whole team can be on the same page when you are talking about it. e.g. ADR, HLD, LLD, SSO and etc.

That’s all, for now, folks, hope it can help you to spin up good documentation really fast and easy, it certainly helped me before.

--

--

--

Adventurer, dreamer and passionate by life. BJJ Black belt, Poker Player. 🇧🇷🇬🇧 Soft Dev Manager as a hobby. Dad of a gorgeous girl and a 🐺 Border Collie.

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Java Database Connectivity in NetBeans IDE and MYSQL workbench

Microsoft Azure basic terms and Different aspects of Azure Storage

How to make access to my remote machines more efficient?

Food for Agile Thought #148

Mobile Testing Strategy for Enterprise apps

Google Pay passes without a backend server

How to Hire a Web Developer: Hello, World

Jupyter Notebook to PDF on Google Colab in just a few lines

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Jeff Cechinel

Jeff Cechinel

Adventurer, dreamer and passionate by life. BJJ Black belt, Poker Player. 🇧🇷🇬🇧 Soft Dev Manager as a hobby. Dad of a gorgeous girl and a 🐺 Border Collie.

More from Medium

Top 10 Experts Tips for DBA to Make Database Secure and Faster

make database faster

Why Software Development is a Never-Ending Process?

Building Software Architecture is Fun but not a Game.

Weekly Digest #59