How to document microservices?
Some history
In 2017, while building a brand new digital platform, we were looking for a way to document our microservices. Sprint after sprint, progressing thru our backlog full of nice stories, I kept producing those event-driven diagrams to clarify responsibilities and interfaces of our microservices. The microservices were based on Domain-Driven Design‘s bounded context and had been design after running event storming sessions. The diagrams surely had benefits with the devs since this was the first time we were building digital products with fully event-driven microservices. But after a few months, it was clear that we needed some help.
The microservice canvas
Building our microservices, specs were mainly residing in multiple stories. This can be challenging to have the PO, functional analyst and team lead document a specific microservice. This is when we came across this article where authors presented a great documentation canvas for microservices: Streamlined Microservice Design in Practice
Our new functional analyst immediately started documenting microservices following this canvas and very quickly, we had a well documented set of microservices. The sad part was that this was all done in Word. But nevertheless, we had something, printed copies (yak, i know!) were all over the place and we could get a sens that every one was beginning to understand what we were building.
Improvement by Author Chris Richardson
Recently, working on an another platform for a successful startup, we did document the microservices with the canvas but this time, everything was put in a Confluence space. Better then Word u will tell me but i think it’s still not optimal. As for tracking decision records, the best place to document microservices is still to me near the code repository. I think author Chris Richardson nailed it in is February 2019 in is article Documenting a service using the microservice canvas. He tweaked the canvas and his example in github as a readme file is really the way to go. He even created a self documenting library. In are quest for IFTTT-style developer platforms, this is must and where we must be heading.
Biggest benefit
My goal for documenting microservices has always been to make it easy for futur squad members to find out what’s been built before. I was also convinced it would facilitate improvements and evolution. But overtime, i realized that the biggest benefit was actually having POs, stakeholders, analysts, devs and even management all working in a microservice/product mindset and all understanding what’s being built. This brings us where we need to be ultimately, having a well documented backlog that everyone understands and linking value and funding to the microservice development.
Next Post