Microservices and Knowledge Sharing

We live in a complex world of event-driven architectures using polyglot microservices developed by self-organizing teams. In such a context, it is virtually impossible to keep up the pace using traditional ways of documenting the code, and making it available to the teams in your organization. Unless of course you would be willing to invest a large amount of time and resources in keeping every team’s APIs, release notes, designs, technical explanations, etc. up to date.

So on one hand we can’t really invest in good detailed documentation, yet on the other hand we do expect the documentation to be available when we need it.

Manual transcription vs automation

If your work involves programming microservices, then most likely there will be many teams in your organization. What if every team in your organization would have to constantly create and maintain its internal documentation in order for it to be always up to date, and always reliable… That kind of effort would be a huge investment.

80% of the effects come from 20% of the causes
– the Pareto Principle

The Pareto Principle helps us to realize that the majority of results come from a minority of inputs. So, another approach would be to automate most of the internal documentation, to cover 80% of the knowledge required for most cases.
Obviously some nudging here and there would be needed in order to make the remaining 20% of the required knowledge available on your developer portal.

By automating the internal documentation your developers will have more time to focus on writing features. And because the documentation is guaranteed to be available and up to date, development will be able to improve the quality of the delivered features.

A single developer portal

Imagine as a developer you have to create a new feature where you need to integrate with another team’s code. For instance, you need to subscribe to a certain message which is published by the other team’s microservice, and when you receive that message, then you need to make a REST call to the other team’s microservice.

• Where do you find the technical information needed to get started?
• Is there an easy to find overview of the REST APIs?
• Do you know which messages are published and what payloads they have?
• Are you sure the other team has already finished development on the required message and REST api, and whether the code was deployed?

Different self-organizing teams will have different traditions. When it comes to documentation, some teams will use a wiki, others will use a specific tool or several tools combined, some might even have no written documentation and stick to meetings or verbal communication, etc.
As a result, developers will often waste a lot of time trying to find the necessary information just to get started.

Finding the information you look for, is a lot easier when using a single developer portal with access to the documentation of all development teams.
Everyone in your organization would know where to start looking for information and how to navigate it.
Of course, teams could still use specific tools which are specialized in documenting a certain technology. As long as the developer portal is able to link to the external tool.

Dealing with different APIs and different technologies

When you have a large architecture with many microservices, you will likely end up with a mixed bag of technologies.
Your organization potentially uses multiple programming languages. Perhaps there is an old technology which is slowly being replaced by something new. Or maybe you are using a combination of technologies such as REST, gRPC and GraphQL.

Now every technology typically has its own way to document its API. Which means that developers will need to look at different systems to find information, and afterwards somehow combine all that knowledge to have an overview. Needless to say that combining in your head the knowledge of all technologies used in multiple microservices is no easy feat.

By visualizing information, we turn it into a landscape that you can explore with your eyes, a sort of information map. And when you’re lost in information, an information map is kind of useful.
– David McCandless

Alternatively, your developer portal could be a dashboard which provides access to all APIs. It could visualize that otherwise mental image which developers would have to create. And allow the users to easily navigate the documentation to present both a high-level combined view as well as enable a drill down into the itty-bitty technical details.

A developer portal powered by automated documentation

We demonstrated the problems with traditional documentation:

• manual transcription is a costly time-consuming activity which leads to outdated unreliable documentation
• finding information is hard when teams use different ways of documenting
• a large architecture inherently will have multiple technologies with different types of APIs

With contextmap, we’ve tried to fix the previously mentioned issues.

• We automate the process of creating documentation to ensure that it is always accurate and up to date
• The developer portal is recognizable to all teams making it easy to navigate and search
• We provide a single access point for all your APIs regardless of the technology