Over the , we've discovered key points that you have to keep track of in order to and . Check out these simple rules down below. years of working with microservices maintain good visibility be able to manage microservices Summary Have an automated API interface documentation Document release notes and related services Define service owners for better communication Document the dependencies of each service Track your API consumers Keep track of intents for changes of the services A bonus tool to solve these problems 1. Have an automated API interface documentation There are many tools out there to API the . This approach is a clear winner compared to manual API documentation because: generate documentation from code the documentation does not get as it's generated frequently without any effort besides a few comment lines in the code, outdated some even without setting up all of the request parameters in an external tool or terminal. tools allow making requests There are a lot of libraries to use depending on the programming language of a particular service. I like using tools that generate Swagger documentation that I can as well import to Postman if needed. 2. Document release notes and related services Companies have different approaches on how to manage their release notes. Some companies do manage them, others do it only on the customer-facing level, but there is another point that people barely speak about. : imagine you have a change in your microservice-based application that involves multiple services to be updated as well as some other side services/dependencies updated. Real-life example to communicate, list the services, update them. The process can take a long time All the technical information is usually not well documented in one place. have to be involved in delivering the information about what version to release and in what sequence . A number of teams every time A simple to that might be implementing a process of writing the technical release notes. All of the needed updates for microservices and the dependencies should be listed there. solution 3. Define service owners for better communication An overview of service ownership is well delivered . in this article The point of the article is that: Each team is responsible for one or more business functions (e.g. business capabilities). A team owns (has sole responsibility for changing) a code base consisting of one or more modules. Its code base is sized so as to not exceed the cognitive capacity of team. The team deploys its code as one or more services. A team should have exactly one service unless there is a proven need to have multiple services. But there is a trick that fewer people talk about. How much effort does it take to find out specific people that you need to talk about feature XYZ? How much time does it take to communicate to other teams? : After you have the teams defined it's necessary to link each microservice or group of microservices to the teams and the roles and responsibilities. Another way is to create a new channel in your corporate messenger. Next time a developer or an architect needs to make a change, he opens that document and sees the contacts instantly. Solution document 4. Document the dependencies of each service Sometimes there can be situations when developers do not clearly document the dependencies or what's the interaction with the dependencies  —  a simple example is a messaging queue. : a typical scenario is that the structure of the messages that are inside the queue is not well documented and people have to examine the source code in order to understand it fully. They spend time and energy to do that over and over when that information is required. Real-life example In today's world, it is important to document structured interactions and services that need to be self-hosted as well as their configuration descriptions. document as much information as you can that may be required in the future about the microservices dependencies to speed things up. Solution: 5. Track your API consumers The services are interrelated and it is important to keep track of the consumers of the APIs. Metrics to monitor: number of requests, average latency of the requests, error messages, API partners, clients, or consumers. In order to modify the services, the developers must have an overview of the API consumers not to break something unintended. : How can this be achieved? One scenario is to use partner keys, JWTs, or any other tokens that will identify the users of the API and from there you will be able to track the use cases. Solution There are solutions to this problem such as: OpenZipkin - it lets you trace the latency between services, Datadog - it lets you monitor metrics and logs, Sentry - it lets you monitor the errors coming from the services. There are plenty of more tools out there that you can find. 6. Keep track of intents for changes of the services When a microservice is developed it does not stop in its final state. The service lives a long life, is maintained, and modified. When other teams, developers, or architects are looking at the interfaces and want to integrate with a service, they typically have no clue how the service might change over time. The service might: get replaced by a new one in the near future, introduce new endpoints that would solve other team's use-case better, be already deprecated and another service would be preferred if new integrations are developed. Imagine if a team starts building a new service, spends half a year to find out that there is now a much better way to achieve that purpose? : In order to fix that problem of reinventing the wheel in the same organization, a brief summary of goals for the next 3/6/12 months should be documented. The summary must be visible and attached to the microservice description. Solution 7. A bonus toolbox to solve these problems As you read this we are working on our microservice documentation toolbox to make all of the above problems disappear. Check it out and join our waiting list! mTools If you made it to the end, hope this article was informative! Take care!

Instantly

Sentry

Trace

Get Early Access

Read My Stories

Too Long; Didn't Read

Developers: Build Less. Deliver More. [Learn how]	

Simple Framework To Document Microservices And A Bonus Tool 🚀

Too Long; Didn't Read

Companies Mentioned

mTools

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

Simple Framework To Document Microservices And A Bonus Tool 🚀

Too Long; Didn't Read

Companies Mentioned

mTools

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES