I will assume you are at least familiar with the concept of microservices — loosely coupled services that provide discrete solutions to business use cases that you can combine to solve current needs and demand. The architectural pattern has gained popularity over the past years, and although not everyone is completely sure what “doing it right” looks like, it’s a concept that suits modern needs and is here to stay for the foreseeable future.
I help organize the Write the Docs (a global community for those interested in technical documentation) group in Berlin. Over the past month, multiple people asked me about what tools and practices I recommend for documenting microservices and application architectures that use the pattern.
Some light Googling later, I found others asking the same question, but no concrete recommendations, so thought it was time to set ideas down. I intend this post to set out the problem, pose some solutions and provoke discussion for those in the field. These are merely my musings, but together we can determine what best practice might be, and create ideas for actual tooling to help.
Read more at Codeship
