Quote:
Originally Posted by suzzer99
If I use a node util that uses 10 other first-level sub-packages, it doesn't have to explain to me how it uses all those sub-packages. I can go to the readmes of those packages if needed.
This isn't typically how a large system is structured though - if you have 100 UI apps and 100 microservices, it may or may not obvious how they are working together and which are the important apps that are coordinating the other apps and which are apps and services are features and so on. Package management dependencies are easy to manage (well for some definition of easy), but service and data dependencies are unlikely to managed this way. You're also assuming that everyone is using node - the larger the system gets and the more it embraces the microservice culture/architecture, the more unlikely it is that you'd be familiar enough with the dependency management system used by every single component in your system. Often you have applications that are collaborating and communicating in fairly intricate ways - consider all the components in a complex machine learning data pipeline - that are not obvious when you're looking at the pieces in isolation.
Another issue is that the larger the system and the more complex the domain, the greater the likelihood that you'd need to collaborate with domain experts on documentation, where external systems like wikis or issue-tracking systems easily win over markdown stored in repos.
I personally favor mono-repo and having all technical design doc in that repo so that code changes and documentation changes can be reviewed together but what typically happens when you have lots of repos, lots of applications, which also means lots of different teams doing their own thing without anyone else knowing, is that things leak outside of repos as people build and use their own documentation solutions and are no longer aware of how other teams are doing things.