Created a new API, great, but what do I need as documentation?
🔥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.
