Getting people to maintain documentation is hard. For me there's two distinct areas of documentation, code level and business level. Business level documentat

Getting people to maintain documentation is hard. For me there's two distinct areas of documentation, code level and business level. Business level documentation is about the higher level logic and processes, and something that I don't regularly see being done well. You'll quite often find that decisions were made in meetings and, while it was minuted, no one can find the minutes when they're needed (or worse they can find conflicting decisions made at different meetings). Code level documentation is about the actual code base and certainly takes a bit of work and commitment from a team to keep up to date. It's very easy for code to slowly slip away from the documentation, which will cause confusion when working with the code in the future. Worst case you can always look at the code to figure out what it's doing, comments may attempt to tell you why it's doing something, but you can't trust them 100%. One thing I like about OpenAPI/Swagger is that you can actually get your microservices to use them so it knows what APIs it has, what parameters they require and what the criteria is for those parameters. By actually using the API definition in that way you can make sure that your APIs and their parameters have to be documented and up to date (at least to from the point of view of methods, endpoints and parameters and their validation criteria).