Simple Framework To Document Microservices And A Bonus Tool 🚀

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.

Summary

1. Have an automated API interface documentation
2. Document release notes and related services
3. Define service owners for better communication
4. Document the dependencies of each service
5. Track your API consumers
6. Keep track of intents for changes of the services
7. A bonus tool to solve these problems

1. Have an automated API interface documentation

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:

1. the documentation does not get outdated as it's generated frequently without any effort besides a few comment lines in the code,
2. some tools even allow making requests without setting up all of the request parameters in an external tool or terminal.

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.

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. 

1. All the technical information is usually not well documented in one place. 
2. A number of teams have to be involved in delivering the information about what version to release and in what sequence every time.

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.

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 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.

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.

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.

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:

1. number of requests,
2. average latency of the requests,
3. error messages,
4. 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. 

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:

1. OpenZipkin - it lets you trace the latency between services,
2. Datadog - it lets you monitor metrics and logs,
3. 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:

1. get replaced by a new one in the near future,
2. introduce new endpoints that would solve other team's use-case better,
3. 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?

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.

7. A bonus toolbox to solve these problems

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!

Take care!