Top three considerations when documenting a microservice
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 comprehensiveIn 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.