Lack of getting started examples for validating PowerShell objects

[shivtorov]

The module is positioned as a tool to validate:

• infrastructure as code
• objects using PowerShell rules

However, Getting started documentation/scenarios do not cover the latter case's basic usage examples.

Documentation starts with a Fruits example, which, in my opinion, is a bit too abstract for an average PowerShell user to relate to their real-world needs. And then, the article jumps straight to advanced infrastructure-as-code validation scenarios. There are no 'Hello World' examples for an average PowerShell user = a junior/mid admin (with no/limited dev experience and with no readily available cloud infrastructure labs) to try out the module capabilities.

IMHO, PSRule can attract more users if you add some copy/pastable examples relevant to junior admins.

Something like:

# to validate started/stopped status of local win services
Get-Service | Invoke-PSRule -Path C:\Temp\winServiceStatus.Rule.ps1

# to validate login and mail attributes format/characters/whitespaces 
Get-ADUSer | Invoke-PSRule -Path C:\Temp\myUsers.Rule.ps1

Another aspect is the lack of end-to-end examples for the reporting side. An average PowerShell user often needs validation reports in a format consumable by non-technical users. E.g. a consultant needs to run a quick customer infrastructure assessment and provide the customer with a remediation report in Excel/Html. An example showing off CSV/HTLM output in the 'Getting Started' section seems pretty useful for module users mentioned above.

[BernieWhite]

@shivtorov Thanks for the feedback. We have been working on improving the documentation but it is still ongoing particularly in the readme.

I assume you found https://microsoft.github.io/PSRule/v2/authoring/writing-rules/

If not maybe that helps out.

[shivtorov]

What I was trying to say is that the provided examples and tutorials assume quite a few prerequisites:

• reader needs access to a non-empty Azure subscription / GitHub repo / ...
• reader is expected to know how to access these cloud resources via PowerShell modules and already solved auth (MFA/etc) challenges associated with connecting to cloud infrastructure

My suggestion is to add a couple of examples to the tutorial that are ready to run if the module user has only a client PC. I.e. the only prerequisite is to install the module.

Such examples can demo the module capabilities by performing some verifications on file system items, windows services, windows event log entries, etc - something that does not require any setup/prep, something that already readily available out of the box for every PowerShell user