We build microservice documentation and management software
Over the years of working with microservices, we've discovered key points that you have to keep track of in order to maintain good visibility and be able to manage microservices. Check out these simple rules down below.
There are many tools out there to generate API documentation from the code. This approach is a clear winner compared to manual API documentation because:
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.
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.
Real-life example: 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.
The process can take a long time to communicate, list the services, update them.
A simple solution 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.
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 time does it take to communicate to other teams? How much effort does it take to find out specific people that you need to talk about feature XYZ?
Solution: After you have the teams defined it's necessary to link each microservice or group of microservices to the teams and document 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.
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.
Real-life example: 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.
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.
Solution: document as much information as you can that may be required in the future about the microservices dependencies to speed things up.
The services are interrelated and it is important to keep track of the consumers of the APIs.
Metrics to monitor:
In order to modify the services, the developers must have an overview of the API consumers not to break something unintended.
Solution: 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.
There are solutions to this problem such as:
There are plenty of more tools out there that you can find.
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:
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?
Solution: 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.
As you read this we are working on our microservice documentation toolbox mTools to make all of the above problems disappear. Check it out and join our waiting list!
If you made it to the end, hope this article was informative!
Create your free account to unlock your custom reading experience.