enhance documentation on writing policy

[ilrudie]

What would you like to be added:

Please add information, tips and recommendations about writing policy.

Why is this needed:

Worked with a magtape user today who had an issue with their new policy. The problem they had was pretty easy to make, easy to overlook and difficult to understand based on the errors shown in the logs. Enhanced documentation on writing policy would probably help with this.

[ilrudie]

Where does the doc belong? Some ideas in no particular order:

• docs/policies.md - add a new section on writing rego/policy. Likely would want to nest the existing descriptions of existing polices under a level 2 heading called "included policies" or something similar.
• CONTRIBUTING.md - doesn't necessarily fit with this content however it would be a place new users might look for it.
• policies/README.md - create a new file in the policies directory to house this information.

[phenixblue]

2 more options come to mind for me:

• Add new policy contribution docs to a new file at docs/policy-contrib.md
• Rename existing docs/policies.md to docs/core-policy-description.md and add new contrib docs at docs/policies.md

[ilrudie]

Contributing is actually maybe a word to avoid here. Some folks may just want to write some policy for their own use and not contribute it. It's possible they wouldn't consider to look in a file called contributing.

Your idea to rename the existing doc to docs/core-policy-description.md and use docs/policies.md for this is pretty good on. I like that. I also think the README.md under policies might be a good place for it and fits with the existing pattern of the README.md under testing.

[phenixblue]

Yeah, good point...contributing probably isn't what we want.

It's more policy development/framework/requirements.

I think you're on the right path, feel free to move forward. I think I'm ok with either of the last 2 suggestions.