Add documentation on PSRule features #68

README.md

@@ -1,9 +1,16 @@
 # PSRule
 
-A cross-platform PowerShell module (Windows, Linux, and macOS) with commands to validate objects on the pipeline using PowerShell syntax.
+A cross-platform PowerShell module (Windows, Linux, and MacOS) with commands to validate objects on the pipeline using PowerShell syntax.
 
 ![ci-badge]
 
+Features of PSRule include:
+
+- [Extensible](docs/features.md#extensible) - Use PowerShell, a flexible scripting language.
+- [Cross-platform](docs/features.md#cross-platform) - Run on MacOS, Linux and Windows.
+- [Reusable](docs/features.md#reusable) - Share rules across teams or organizations.
+- [Recommendations](docs/features.md#recommendations) - Include detailed instructions to remediate issues.
+
 ## Disclaimer
 
 This project is to be considered a **proof-of-concept** and **not a supported product**.

docs/features.md

@@ -0,0 +1,44 @@
+# PSRule features
+
+The following sections describe key features of PSRule.
+
+- [Extensible](#extensible)
+- [Cross-platform](#cross-platform)
+- [Reusable](#reusable)
+- [Recommendations](#recommendations)
+
+## Extensible
+
+Authors define rules using PowerShell, a flexible scripting language. If you or your team already can write a basic PowerShell script, you can already define a rule. What's more, you can leverage a large world-wide community of PowerShell users with scripts and cmdlets to help you build out rules quickly.
+
+## Cross-platform
+
+PSRule uses modern PowerShell libraries at it's core, allowing it to go anywhere Windows PowerShell 5.1 or PowerShell Core 6.2 can go. PSRule runs on MacOS, Linux and Windows.
+
+To install PSRule use the `Install-Module` cmdlet within Windows PowerShell or PowerShell Core.
+
+```powershell
+Install-Module -Name PSRule -Scope CurrentUser;
+```
+
+PSRule also has editor support for Visual Studio Code with the companion extension, which can be installed on MacOS, Linux and Windows.
+
+To install the extension:
+
+```text
+code --install-extension bewhite.psrule-vscode-preview
+```
+
+For additional installation options see [install instructions](scenarios/install-instructions.md).
+
+## Reusable
+
+Define rules once then reuse and share rules across teams or organizations. Rules can be packaged up into a module then distributed.
+
+PSRule uses PowerShell modules as the standard way to distribute rules. Modules containing rules can be published on the PowerShell Gallery or network share using the same process as regular PowerShell modules.
+
+## Recommendations
+
+PSRule allows rule authors to define recommendations in markdown. This allows not only the cause of the issue to be identified but detailed instructions to be included to remediate issues.
+
+For more information see [about_PSRule_docs](concepts/PSRule/en-US/about_PSRule_Docs.md).

docs/scenarios/install-instructions.md

@@ -3,7 +3,7 @@
 ## Prerequisites
 
 - Windows PowerShell 5.1 with .NET Framework 4.7.2+ or
-- PowerShell Core 6.0 or greater on Windows, macOS and Linux
+- PowerShell Core 6.2 or greater on Windows, MacOS and Linux
 
 For a list of platforms that PowerShell Core is supported on [see](https://github.com/PowerShell/PowerShell#get-powershell).