Turn "Read the Source to Understand It" into Documentation Someone Can Actually Operate From — for Any PowerShell Module

Get-ContosoComputerInventory

Synopsis

Retrieves operating-system inventory from one or more Windows computers.

Description

Get-ContosoComputerInventory queries the Win32_OperatingSystem CIM class on each specified computer and returns one result object per computer.

The command does not terminate the entire operation when an individual computer cannot be queried. Instead, it returns a result object with a Status value of Failed and places the associated exception message in ErrorMessage.

The command requires network connectivity and permission to perform remote CIM queries on each target.

Syntax

Get-ContosoComputerInventory
    [-ComputerName] <String[]>
    [<CommonParameters>]

Parameters

ComputerName

Specifies one or more computers to query.

The parameter:

• Is mandatory
• Accepts multiple values
• Accepts pipeline input
• Accepts pipeline input by property name
• Supports the aliases CN and Name
• Rejects null or empty values

Type: System.String[]
Required: True
Position: Named
Default value: None
Accept pipeline input: True
Accept wildcard characters: False

Inputs

System.String

You can pipe computer names to this command.

Objects containing a ComputerName, CN, or Name property may also bind by property name.

Outputs

System.Management.Automation.PSCustomObject

The command returns one object per computer with the following properties:

Example 1 — Query One Computer

Get-ContosoComputerInventory `
    -ComputerName 'SERVER01'

Queries SERVER01 and returns its operating-system inventory.

Example 2 — Query Multiple Computers

Get-ContosoComputerInventory `
    -ComputerName 'SERVER01', 'SERVER02'

Returns one result object for each named computer.

Example 3 — Use Pipeline Input

'SERVER01', 'SERVER02' |
    Get-ContosoComputerInventory

Pipes computer-name strings to the command.

Example 4 — Use Property-Name Binding

Import-Csv '.\computers.csv' |
    Get-ContosoComputerInventory

This example works when the CSV contains a column named ComputerName, CN, or Name.

Notes

• The command uses CIM remote access.
• The executing identity must have permission to query the target computer.
• Failed queries return failure objects rather than terminating the full pipeline.
• The ErrorMessage property may contain internal system details and should be handled appropriately before sharing reports externally.
• Wildcards are not implemented for ComputerName.

Related Links

• Export-ContosoComputerInventory
• Get-CimInstance

# ContosoInventory

ContosoInventory is a PowerShell module for collecting and exporting
Windows computer inventory through CIM.

## Features
- Query one or more Windows computers
- Accept pipeline input
- Return structured success and failure results
- Export inventory reports
- Support Windows PowerShell 5.1 and PowerShell 7 where tested

## Requirements
- Windows PowerShell 5.1 or a supported PowerShell 7 release
- Network access to target computers
- CIM remoting enabled
- Permission to query the target systems

## Installation
```powershell
Install-Module `
    -Name ContosoInventory `
    -Repository PSGallery `
    -Scope CurrentUser
```

## Import
```powershell
Import-Module ContosoInventory
```

## Quick Start
```powershell
Get-ContosoComputerInventory `
    -ComputerName 'SERVER01'
```

## Commands
| Command | Description |
| Get-ContosoComputerInventory | Retrieves computer inventory |
| Export-ContosoComputerInventory | Exports inventory results |

## Documentation
- Command reference
- Authentication and permissions
- Troubleshooting
- Known limitations
- Changelog

## Security
The module does not require stored credentials. It uses the caller's current authentication context unless otherwise documented.

## Support
Open an issue in the approved repository and include:
- Module version
- PowerShell version
- Operating system
- Sanitized error message
- Reproduction steps

The actual README should reflect the module's confirmed distribution and support model.

function Verb-Noun {
    <#
    .SYNOPSIS
    Provides a concise one-sentence description.

    .DESCRIPTION
    Explains what the command does, how it behaves, and any important
    operational constraints.

    .PARAMETER Name
    Describes the value, format, default behavior, and effect.

    .EXAMPLE
    Verb-Noun -Name 'Example'
    Explains the result of the example.

    .INPUTS
    System.String

    .OUTPUTS
    Namespace.TypeName

    .NOTES
    Requires PowerShell 7.2 or later.
    Requires permission to read the target resource.

    .LINK
    https://approved-documentation-location
    #>
    [CmdletBinding()]
    param()
}

Comment-based help should describe behavior, not duplicate syntax that PowerShell already generates.

Install PlatyPS:

Install-Module `
    -Name Microsoft.PowerShell.PlatyPS `
    -Scope CurrentUser

Import the module being documented:

Import-Module `
    -Name '.\ContosoInventory.psd1' `
    -Force

Create Markdown help:

New-MarkdownCommandHelp `
    -ModuleInfo (
        Get-Module ContosoInventory
    ) `
    -OutputFolder '.\docs\commands'

Update existing Markdown help:

Update-MarkdownCommandHelp `
    -Path '.\docs\commands'

Create external help:

New-ExternalHelp `
    -Path '.\docs\commands' `
    -OutputPath '.\en-US' `
    -Force

Exact commands may differ by PlatyPS version. The build pipeline should pin and test the documentation-tool version.

Check Exported Command Coverage

$exportedCommands = Get-Command `
    -Module 'ContosoInventory' `
    -CommandType Function, Cmdlet

$helpFiles = Get-ChildItem `
    -Path '.\docs\commands' `
    -Filter '*.md'

$documentedNames = $helpFiles.BaseName

Compare-Object `
    -ReferenceObject $exportedCommands.Name `
    -DifferenceObject $documentedNames

Check Help Availability

foreach ($command in $exportedCommands) {
    $help = Get-Help -Name $command.Name -Full
    [pscustomobject]@{
        Command = $command.Name
        SynopsisPresent = -not [string]::IsNullOrWhiteSpace(
            $help.Synopsis
        )
        ExamplesPresent = @($help.Examples.Example).Count -gt 0
        ParametersPresent = @($help.Parameters.Parameter).Count -gt 0
    }
}

Check Parameter Coverage

$command = Get-Command Get-ContosoComputerInventory
$help = Get-Help Get-ContosoComputerInventory -Full

$implementedParameters = $command.Parameters.Keys |
    Where-Object {
        $_ -notin [System.Management.Automation.PSCmdlet]::CommonParameters
    }

$documentedParameters = @(
    $help.Parameters.Parameter.Name
)

Compare-Object `
    -ReferenceObject $implementedParameters `
    -DifferenceObject $documentedParameters

Common and optional common parameters may require additional filtering.

Check Examples

Examples should be validated by:

• Parsing them
• Running safe examples
• Mocking external systems
• Confirming parameter names
• Confirming expected output
• Checking placeholder consistency
• Ensuring no secrets are present

Do not automatically execute state-changing documentation examples against production systems.

Review these fields:

@{
    RootModule
    ModuleVersion
    GUID
    Author
    CompanyName
    Copyright
    Description
    PowerShellVersion
    CompatiblePSEditions
    RequiredModules
    RequiredAssemblies
    ScriptsToProcess
    TypesToProcess
    FormatsToProcess
    NestedModules
    FunctionsToExport
    CmdletsToExport
    VariablesToExport
    AliasesToExport
    PrivateData
    HelpInfoURI
}

Avoid broad exports such as:

VariablesToExport = '*'

unless intentionally required. Documentation review may reveal module-design issues that should be corrected separately.

A changelog should help users determine whether an upgrade is safe.

Example:

# Changelog

## 1.3.0

### Added
- Added pipeline-by-property-name support to
  `Get-ContosoComputerInventory`.

### Changed
- Improved failed-query result objects with a `Status` property.

### Fixed
- Corrected handling of computer names containing hyphens.

### Deprecated
- `Export-ContosoLegacyInventory` is deprecated and will be removed
  in version 2.0.0.

### Security
- Removed plain-text credential parameters.

### Breaking Changes
- The `Result` property was renamed to `Status`.

### Migration
Replace:
```powershell
$result.Result
```
with:
```powershell
$result.Status
```

Versioning Guidance

Document whether the module uses semantic versioning or another strategy. Under semantic versioning:

• Major: breaking public-interface changes
• Minor: backward-compatible functionality
• Patch: backward-compatible fixes

Potential breaking changes include: renaming commands, renaming parameters, removing aliases, changing output properties, changing output types, changing default behavior, changing authentication requirements, dropping a PowerShell version, changing error behavior, removing pipeline support. Documentation changes should ship with the code change they describe.

Migration Documentation

For each breaking change, include: (1) What changed, (2) Why it changed, (3) Affected versions, (4) Old syntax, (5) New syntax, (6) Output changes, (7) Behavior changes, (8) Required permission changes, (9) Required configuration changes, (10) Rollback considerations.

## Migrating from 1.x to 2.0

Version 2.0 removes the `-Credential` parameter. Unattended
automation must use managed identity or certificate-based authentication.

### Before
```powershell
Connect-ContosoService -Credential $credential
```

### After
```powershell
Connect-ContosoService -CertificateThumbprint $thumbprint
```

Contribution Guide

A contribution guide may define: branching model, coding style, approved verbs, formatting rules, PSScriptAnalyzer configuration, Pester requirements, documentation requirements, example requirements, security review requirements, changelog requirements, pull-request process, review ownership, release process, breaking-change approval.

Every public command change must include corresponding updates to:
- Comment-based help
- Markdown command reference
- Examples
- Changelog
- Pester documentation coverage tests

Documentation itself can expose sensitive information.

Do not include:

• Real credentials
• API keys
• Access tokens
• Private keys
• Internal-only tenant IDs
• Customer names
• Private hostnames
• Sensitive IP addresses
• Confidential network paths
• Security-tool bypass instructions
• Unapproved endpoints
• Internal incident details
• Real personal data
• Full production error payloads

Use safe placeholders:

TENANT_ID
APPROVED_SERVER
SERVICE_ACCOUNT
CERTIFICATE_THUMBPRINT
https://api.example.invalid

Also avoid documenting insecure workarounds such as:

• Disabling certificate validation
• Broadly disabling firewalls
• Running every command as Domain Admin
• Storing credentials in source
• Suppressing all errors
• Trusting every repository
• Bypassing execution controls