How to automatically manage documentation

Question

Our project consists of a cluster of microservices (let's say 20, mainly JS & PHP) that are communicating among themselves and exchanging data (via MQ) among themselves. Also, clusters have API available to other teams. So microservices process either our requests or API requests.

A while ago our team agreed to have our cluster documented, so

1. we would be able to onboard newcomers quicker
2. we would have a better overview of the structure of our cluster
3. other teams will be able to make sense of our project by the bird-eye view
4. other teams will have access to the API documentation for better usability

We, however, had encountered a foreseeable obstacle -> it is pretty painful and time-consuming to keep all parts of documentation up to date.

So here is our document structure:

• Overview => this is a flowchart with the flow of the data across microservices. This is done manually in diagram software with idea that flow will change very infrequently and I would say that is fine.
• Microservice documentation => this is also a manually created diagram, describing the inner workings of the single microservice since the service usually contains a couple of classes. This is basically for internal purposes (see points 1 & 2). But there is the aforementioned problem becoming visible -> since diagrams are done manually, any change in codebase will break them. Yes, we tried to make the diagrams not too much detailed, so small changes won't affect the bigger picture in diagrams. But the still static, manually created diagram is very dependent on the codebase and depends on the discipline of the team to keep diagrams updated. So this is problem #1.
• Configuration => There are around 30 configuration parameters that supply microservices with settings or directions specific service should behave. This configuration is set either by us or by other teams in case of API use. So documentation needs to be clear and polished for all stakeholders. Similar to the previous point, these parameters change relatively frequently and needs to be kept up to date. There comes problem #2.

So my question would be, how would you handle such documentation?

I am pretty sure we are not the only team under the sun that uses microservices and needs to have their project covered by understandable documentation.

Problem #1 is documentation of data flow within a single microservice. Basically opening a black box

Problem #2 is documentation of configuration parameters. These are used for behaviour directives for specific microservices.

We are looking for processes or approaches (and consequently technical solutions), that would at least partially automate this documentation creation and management.

Thank you all for sharing your solutions and all your suggestions.

Answer 1

Your question is very broad and cannot be answered in detail. However, here some advices:

1. The general overview can be very useful, but can quickly degenerate into very abstract literature or unreadable diagrams. A good way to avoid this is to replace it with a set of ADR (Architecture Decision Records), that document important decisions when they are made.
2. The API documentation is best automated using doxygen, javadoc or a similar tool. Since it's based on extracted comments, there is a higher chance that the content will be updated with the code.
3. Configuration parameters could get a similar treatment. But unfortunately, parameters' effect is often complex and programmed far away from their definition. There is therefore no benefit to extract documentation from the comments. As it is really part of the product and of high value for the users, it would be worth to invest in some separate, manually crafted, text files.
4. Keep diagramming light. Diagrams are time consuming to maintain in parallel to the code and are often out of sync. Most developers will have a look at the beginning to get and understanding of the sketch/outline some complex structures or interactions. They will verify details directly in the code. Therefore, keep your diagrams very simple and reserve them for non obvious things. The current trend by the way, is diagramming as code with the advantage of having your diagram easily versioned with the code.
5. Describing the internal flow of your microservice brings the danger of diagramming all the details of the control flow. Double maintenance and unreadable diagram guaranteed. Use this only to explain the flow that cannot be easily read from the code. For example, in an event-driven architecture, it is sometimes difficult to follow the sequence of events. There a diagram can help to easily grasp what happens and check the details in the code. But if it is for documenting the conditions and loops that anybody could just read in the code, forget it (automate the mess would just lead to an automated mess ;-) ).

Last but not least, there's an excellent book that's really state of the art on this topic and document automation : "Living Documentation: Continuous Knowledge Sharing by Design" by Cyrille Martraire.

Answer 2

Documentation should tell you where the backup is. It should not be the backup.

As such, beware automating the creation of documentation. It's far to easy to create documents that are easy to create and never worth reading. Don't create a situation where changing a setting or line of code always breaks the documentation. Or it'll just end up out of sync.

Rather, you may wish to invest in visualizing tools that make getting reports of the state of things easy. Those will let you watch and record as things change.

Be careful about mixing these two different goals. Word is fine way to document. It's a slow way to produce a report.