Improvements to doco (#42)

README.md

@@ -4,17 +4,26 @@ A suite of rules to validate Azure resources against the Cloud Adoption Framewor
 
 ![ci-badge]
 
-**More to come soon.**
+Features of PSRule for CAF include:
 
-## Disclaimer
+- [Ready to go](docs/features.md#ready-to-go) - Leverage configurable rules to validate Azure resources.
+- [DevOps](docs/features.md#devops) - Validate resources and infrastructure code pre or post-deployment.
+- [Cross-platform](docs/features.md#cross-platform) - Run on MacOS, Linux, and Windows.
 
-This project is to be considered a **proof-of-concept** and **not a supported product**.
+## Support
 
-For issues with rules and documentation please check our GitHub [issues](https://github.com/Microsoft/PSRule.Rules.CAF/issues) page.
-If you do not see your problem captured, please file a new issue and follow the provided template.
+This project uses GitHub Issues to track bugs and feature requests.
+Please search the existing issues before filing new issues to avoid duplicates.
+
+- For new issues, file your bug or feature request as a new [Issue].
+- For help and questions about using this project, we have a Gitter room which you can join below.
+
+[![Join the chat][chat-badge]][chat]
 
 If you have any problems with the [PSRule][engine] engine, please check the project GitHub [issues](https://github.com/Microsoft/PSRule/issues) page instead.
 
+Support for this project/ product is limited to the resources listed above.
+
 ## Getting the modules
 
 This project requires the `PSRule`, `PSRule.Rules.Azure` and `Az` PowerShell modules. For details on each see [install].
@@ -103,7 +112,10 @@ or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any addi
 
 This project is [licensed under the MIT License](LICENSE).
 
-[install]: docs/scenarios/install-instructions.md
+[issue]: https://github.com/Microsoft/PSRule.Rules.CAF/issues
+[install]: docs/install-instructions.md
 [ci-badge]: https://dev.azure.com/bewhite/PSRule.Rules.CAF/_apis/build/status/PSRule.Rules.CAF-CI?branchName=main
 [module]: https://www.powershellgallery.com/packages/PSRule.Rules.CAF
 [engine]: https://github.com/Microsoft/PSRule
+[chat]: https://gitter.im/PSRule/PSRule.Rules.CAF?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+[chat-badge]: https://img.shields.io/static/v1.svg?label=chat&message=on%20gitter&color=informational&logo=gitter

SUPPORT.md

@@ -0,0 +1,18 @@
+# Support
+
+## How to file issues and get help
+
+This project uses GitHub Issues to track bugs and feature requests.
+Please search the existing issues before filing new issues to avoid duplicates.
+For new issues, file your bug or feature request as a new Issue.
+
+For help and questions about using this project, we have a Gitter room which you can join below.
+
+[![Join the chat][chat-badge]][chat]
+
+## Microsoft Support Policy
+
+Support for this project/ product is limited to the resources listed above.
+
+[chat]: https://gitter.im/PSRule/PSRule.Rules.CAF?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+[chat-badge]: https://img.shields.io/static/v1.svg?label=chat&message=on%20gitter&color=informational&logo=gitter

docs/features.md

@@ -0,0 +1,85 @@
+# PSRule for Cloud Adoption Framework features
+
+The following sections describe key features of PSRule for Cloud Adoption Framework (CAF).
+
+- [Ready to go](#ready-to-go)
+- [DevOps](#devops)
+- [Cross-platform](#cross-platform)
+
+## Ready to go
+
+PSRule for CAF includes rules for validating resources against CAF recommendations.
+Each rule includes additional information to help remediate issues.
+
+Use the built-in rules to start enforcing release processes quickly.
+Rules can be configured to customize the implementation for your organization.
+Custom rules can be implemented quickly and work side-by-side with built-in rules.
+
+As new built-in rules are added and improved, download the latest PowerShell module to start using them.
+
+## DevOps
+
+Azure resources can be validated throughout their lifecycle to support a DevOps culture.
+
+From as early as authoring an Azure Resource Manager (ARM) template, resources can be validated offline.
+Pre-flight validation can be integrated into a continuous integration (CI) pipeline to:
+
+- **Shift-left:** Identify configuration issues and provide fast feedback in pull requests.
+- **Quality gates:** Implement quality gates between environments such as development, test, and production.
+- **Monitor continuously:** Perform ongoing checks for configuration optimization opportunities.
+
+## Cross-platform
+
+PSRule uses modern PowerShell libraries at its core, allowing it to go anywhere PowerShell can go.
+The companion extension for Visual Studio Code provides snippets for authoring rules and documentation.
+PSRule runs on MacOS, Linux and Windows.
+
+PowerShell makes it easy to integrate PSRule into popular CI systems.
+Additionally, PSRule has extensions for:
+
+- [Azure Pipeline (Azure DevOps)][extension-pipelines]
+- [GitHub Actions (GitHub)][extension-github]
+
+PSRule for CAF (`PSRule.Rules.CAF`) can be installed locally, within a container, or Azure Cloud Shell.
+To install, use the `Install-Module` cmdlet within PowerShell.
+For installation options see [install instructions](install-instructions.md).
+
+## Frequently Asked Questions (FAQ)
+
+Continue reading for FAQ relating to _PSRule for CAF_.
+For general FAQ see [PSRule - Frequently Asked Questions (FAQ)][ps-rule-faq], including:
+
+- [How is PSRule different to Pester?][compare-pester]
+- [How do I configure PSRule?][ps-rule-configure]
+- [How do I ignore a rule?][ignore-rule]
+
+### Traditional unit testing vs PSRule for CAF?
+
+You may already be using a unit test framework such as Pester to test infrastructure code.
+If you are, then you may have encountered the following challenges.
+
+For a general PSRule/ Pester comparison see [How is PSRule different to Pester?][compare-pester]
+
+#### Unit testing more than basic JSON structure
+
+Unit tests are unable to effectively test resources contained within Azure templates.
+Templates should be reusable, but this creates problems for testing when functions, conditions and copy loops are used.
+Template parameters could completely change the type, number of, or configuration of resources.
+
+PSRule resolves templates to allow analysis of the resources that would be deployed based on provided parameters.
+
+#### Standard library of tests
+
+When building unit tests for Azure resources, starting with an empty repository can be a daunting experience.
+While there are several open source repositories and samples around to get you started, you need to integrate these yourself.
+
+_PSRule for CAF_ is distributed as a PowerShell module using the PowerShell Gallery.
+Using a PowerShell module makes it easy to install and update.
+The built-in rules allow you starting testing resources quickly, with minimal integration.
+
+[compare-pester]: https://github.com/microsoft/PSRule/blob/main/docs/features.md#how-is-psrule-different-to-pester
+[ignore-rule]: https://github.com/microsoft/PSRule/blob/main/docs/features.md#how-do-i-ignore-a-rule
+[ps-rule-configure]: https://github.com/microsoft/PSRule/blob/main/docs/features.md#how-do-i-configure-psrule
+[ps-rule-faq]: https://github.com/microsoft/PSRule/blob/main/docs/features.md#frequently-asked-questions-faq
+[extension-pipelines]: https://marketplace.visualstudio.com/items?itemName=bewhite.ps-rule
+[extension-github]: https://github.com/marketplace/actions/psrule

src/PSRule.Rules.CAF/PSRule.Rules.CAF.psd1

@@ -4,7 +4,6 @@
 #
 # PSRule.Rules.CAF
 #
-
 @{
 
 # Script module or binary module file associated with this manifest.
@@ -31,7 +30,7 @@ Copyright = '(c) Microsoft Corporation. All rights reserved.'
 # Description of the functionality provided by this module
 Description = 'A suite of rules to validate Azure resources against the Cloud Adoption Framework (CAF) using PSRule.
 
-This project is to be considered a proof-of-concept and not a supported product.'
+This project uses GitHub Issues to track bugs and feature requests. See GitHub project for more information.'
 
 # Minimum version of the Windows PowerShell engine required by this module
 PowerShellVersion = '5.1'