HACKER Q&A
📣 shivylp

How do you discover products/services by other teams within your org?


With microservices pattern, in a medium-big organisation, there are lots of services maintained by lot of different teams. And somewhat regularly, new services are created, old services are deprecated, ownerships change, etc. With all this some challenges emerge:

1. Hard for new team members to make sense of the overall system. 2. Repeated efforts: team A does not know team B has solved a particular challenge already and end up building something again. 3. When deprecating a service/API, no one knows who else is using it and the impact of stopping that service/API.

Within your organization, what documentation tools or practices do you follow to be make it easy to discover existing services/products, product PIC for it, tech PIC for it, etc.?

  👤 ndimares Accepted Answer ✓
I've never used any of the products, but there are some interesting developments in the "code visualisation" space, i.e. https://www.codesee.io/. My sense is that right now they're mainly targeting use case #1 that you mentioned, but I'm interested in whether they will grow to be useful for use case #3 which you mentioned.

The project I work on (speakeasyapi.dev) is more focused on the public API side for now, but we've looked at the microservice problem. We've come at it from the angle of providing an SDK which can track the traffic to a service. That way you can be aware of your services true surface area vs. what's documented.

Curious to hear other ways people are solving these problems.

👤 iamdeedubs
It would be worth taking a look at https://backstage.io/

Git based dev portal, lots of interesting modules: - service discovery - swagger / avro rendering - k8s integration (urls, cost est,)

Something like the tech radar in a large org is worth the price of admission IMHO