Azure / Azure/bicep

Show "introductory usage of resource type" in Template Reference

Open
#8,845 1 comment 1 reaction 0 assignees View on GitHub
documentation enhancement Needs: Upvote
Dominant language
Bicep
Stars
3.6k
Forks
830
Avg merge
1d 21m
Merged PRs (30d)
79

Description

I believe this is an issue with the RP specification. It looks like they are reusing a definition when just the id property should have been defined.

We won't be adding a minimum format section because the required flag is not reliable. There are lots of properties that become required when another property is set. So, I think a minimum view would be misleading.

However, we can address this issue by displaying an example that shows an introductory usage of the resource type. It would not be strictly limited to required properties but it would show the minimum properties that are commonly set.

_Originally posted by @tfitzmac in https://github.com/Azure/bicep/issues/8801#issuecomment-1295305816_

Contributor guide

Open the contributing guide

Research direction

Start in the Template Reference and locate where resource types are presented. Add an introductory usage example showing the commonly set properties rather than a minimum-format section; done means the example appears in the generated reference and does not imply that only required properties are valid.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.