Top three considerations when documenting a microservice

by Russell Shurts on Dec 13, 2017 12:00:00 AM

Microservices have changed the way we architect, build, test, deploy, and operate our software. It should be no surprise then that microservices change our approach to software documentation. Following are the top three considerations when documenting a microservice.

1. Make documentation comprehensive

In a microservice environment, each team may be using different programming languages, data storage, and conventions. This means a shared understand of a service not an accident. A shared understanding only occurs due to comprehensive documentation. Comprehensive documentation includes the following:

Description - identify the microservice’s purpose and role.
Architecture diagram - summarize the complexity of the microservice in a picture.
Endpoints - document the public interface.
Dependencies - detail services the microservice relies on and their SLAs.
Runbooks - detail how to handle each possible alert the microservice can generate.
Contact information - who to contact and how to contact them.
Onboarding guide - get new developers introducing changes without hand-holding.
FAQ - common questions and their answers.

While comprehensive documentation may look like a lot, it should not be verbose. Comprehensive documentation seeks to be complete but brief. Its purpose is to increase developer productivity and help resolve issues faster.

2. Update documentation as part of the development cycle

To be useful, software documentation needs to be up-to-date. When exposing a new API, document it. When making a new alert, create a runbook to remedy the alert. When adding a dependency, add it to the list. To keep software up-to-date, elevate it to the same level as code. Update it alongside the code and review it in a pull request with the code. To simplify this, consider keeping a /docs folder in the code with Markdown or reStructuredText documentation. As part of the build process this documentation can be transformed and published to the documentation repository.

3. Use a central location for all microservice documentation

When troubleshooting an issue or trying to determine how a service works, the last thing you want to be doing is looking through code repositories or finding out you don’t have the permissions to view the documentation. Publish all microservice documentation to a shared, centralized location. This ensures the documentation is readily-available. And enables developers to find answers to their own questions and problems. An internal website or wiki is a common place to publish this documentation. Keeping everything in one spot does two things. One, people use the documentation. And, two, it encourages teams to keep their documentation up to the standards of the rest of the teams. Microservices enable rapid change, but without a shared understanding the whole ecosystem suffers. Useful documentation prevents this. The above guideline will help you get there. And set the stage for increased productivity and faster issue resolution. Want to know more about building microservices? Let’s chat, Pythian can help.

No Comments Yet

Let us know what you think

See all

Share this