ResourceModules VS PSDocs

That is a great question, and not the least because it's the one I've been struggling with for the past few years. As for Azure and Bicep, we tried out a few things until we found out about the Common Azure Resource Modules Library (https://github.com/Azure/ResourceModules) and started experimenting on how to leverage that. Wheter you find such modules useful or not, I would suggest taking a look at the module design principles they have (https://github.com/Azure/ResourceModules/wiki/The%20context%20-%20CARML%20library), which I've found to be great.

In general resource group is lifecycle and deployment boundary. So your Bicep or ARM templates should deploy resource groups with all resources included. To make it easier you can use resource modules from https://github.com/Azure/ResourceModules.

For modularized Bicep, I'd suggest you to take a look at Common Azure Resource Modules Library - probably not much of an use right now if you have implemented everything, but could be of use if you feel like refactoring something. I wouldn't suggest it as an example on how to do custom bicep implementation, but one can certainly take some inspiration from there, if not directly using the modules.

What I found is that using the Resource Modules (https://github.com/Azure/ResourceModules) repo is the best approach. It simplifies the authoring quite a lot in my opinion. And every module on the repo is bicep. But since the modules are created by Microsoft/the community, not every resource or service has a ready module. I have been using it for the last 6-8 months, and find it covers 90% of my scenarios. And each module is quite well documented, but in some cases you have to study the module to figure out the required inputs.

We don't have a team in place to update and maintain modules so that's where my thought about CARML comes into the picture. Unsure how this is maintained though and how to update the modules, and i think it makes it more complex and hard to understand for people unfamiliar with IaC.

For Pull Requests, it compiles bicep into ARM templates and runs PSDocs for them an accompaying json file that holds versioning information and, document title and some additional information. Then it looks for ./test/module.test.bicep -file (which is just a copy of a suitable test suite from ResourceModules) and runs psrule against that. For runs triggered from main-branch, it queues the module publishing pipeline for every changed module.bicep found.