I have been working with Bicep a lot on a recent project and I tweeted a reply to a tweet as you can see below, in order to reply properly I decided to write this blog post as hopefully being a way to give constructive feedback.
Lets take the example of vnet peering – if you google/bing for vnet peering bicep you will end up here most likely – https://docs.microsoft.com/en-us/azure/templates/microsoft.network/virtualnetworks/virtualnetworkpeerings?pivots=deployment-language-bicep
This is somewhat helpful in terms of it shows you the format, however it wont help a lot of people as its not got any examples of how it works.
I always use https://github.com/Azure/ResourceModules as I can look at an example, they have deployment examples links for every resource which is like so: –
Now with this example I can see what the values look like and get a feel for what is needed. The first screen shot does explain the values which is ok at best, an example would be good, a common scenario would be even better.
When it comes to documentation examples can be what makes or breaks the documentation.
For me scenarios are the answer to what I would like to see – If I want to create a keyvault, theres every chance I need to create a secret and populate this, maybe I need an access policy or a managed identity to go along with this – these are real work scenarios that the documentation dont cover – yes we can’t cover everything but if we go back to the first screen shot above – this isnt helping me a great deal truth be told.
Now there is a common scenarios page from the Bicep team – https://docs.microsoft.com/en-us/azure/azure-resource-manager/bicep/scenarios-secrets which is a good start, I feel we really need a lot more of these or at least link to github repositories for further help.
When trying to figure out how to get a load balancer to play nicely with 2 virtual machines I had to manually depoy it and then reverse engineer the bicep – the sample in the documentation was a good start, didnt cover what I needed but it was a good start.
Ive had dm’s saying that there isnt enough people with enough time to write all of the scenario’s, which is fine, finding a way to make public contributions of example scenario;s might be one way to go about it.
Either way I feel there is room for improvement on the documentation for a lot of microsoft docs, its an unpopular opinion but there you have it.
If you have questions reach out to me here in the comments below or on twitter.
Don’t forget to subscribe to myYouTube Channel.