Refactor documentation structure and content #111

marko-stanojevic · 2026-01-22T21:55:24Z

Description

This pull request updates the documentation structure for the PowerShell module template, consolidating and modernizing the documentation for improved clarity and onboarding. The main README.md is enhanced with clearer project structure, contribution, and support instructions. Several old documentation files are removed and replaced with a new, comprehensive getting-started.md guide. The documentation directory is reorganized for simplicity and easier navigation.

Documentation Restructuring and Improvements:

The README.md is updated for improved clarity, with a more inviting introduction, clearer project structure, and enhanced contribution/support sections. Documentation links are modernized and grouped for easier access. [1] [2] [3] [4]
The docs/ directory is reorganized: legacy files like docs/help/, docs/building.md, docs/dependencies.md, docs/generating-help.md, docs/maintenance.md, docs/publishing.md, and docs/testing.md are removed and replaced by a new, comprehensive docs/getting-started.md onboarding guide. [1] [2] [3] [4] [5] [6] [7]
The new docs/getting-started.md provides a step-by-step onboarding experience, including prerequisites, setup, project structure, customization, first function creation, development workflow, troubleshooting, and next steps.

Project Structure and Navigation:

The documentation and project structure in README.md and docs/getting-started.md now reflect the current layout, including new and updated directories such as .devcontainer/, .github/, .vscode/, and a simplified docs/ folder. [1] [2] [3]

Contribution and Support:

Contribution guidelines and support instructions in README.md are rewritten for clarity, encouraging broader participation and providing clear next steps for contributors and users.

These changes make the documentation more approachable and easier to maintain, while streamlining the onboarding process for new users and contributors.

Copilot

Pull request overview

Refactors and consolidates the documentation for the PowerShell module template to improve onboarding and simplify navigation.

Changes:

Updates README.md to reflect the current repo layout and point to the new docs structure.
Replaces multiple legacy docs pages with a new comprehensive onboarding guide (docs/getting-started.md).
Expands and modernizes the existing development and CI/CD documentation (docs/development.md, docs/ci-cd.md).

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
README.md	Updates project structure and documentation pointers.
docs/getting-started.md	Adds a new end-to-end onboarding guide.
docs/development.md	Expands development, testing, and documentation-generation guidance.
docs/ci-cd.md	Expands CI/CD, versioning, publishing, and maintenance documentation.
docs/testing.md	Removed; content consolidated elsewhere.
docs/publishing.md	Removed; content consolidated elsewhere.
docs/maintenance.md	Removed; content consolidated elsewhere.
docs/generating-help.md	Removed; content consolidated elsewhere.
docs/dependencies.md	Removed; content consolidated elsewhere.
docs/building.md	Removed; content consolidated elsewhere.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/getting-started.md

Copilot · 2026-01-22T22:07:26Z

docs/ci-cd.md

+- Compiles module with ModuleBuilder
+- Generates help documentation (MAML + Markdown)
+- Creates GitHub Release (if on main branch)
+- Publishes to PowerShell Gallery (optional)


This implies the CI pipeline creates GitHub Releases and optionally publishes to PSGallery on main, but the current ci.yml only runs a Debug build; releases/publishing happen via the separate Release workflow (.github/workflows/release.yml). Please adjust this description accordingly.

docs/ci-cd.md

Copilot · 2026-01-22T22:07:27Z

docs/ci-cd.md

+#### Artifact Cleanup
+
+Automatically removes old build artifacts:
+
+- **Schedule**: Daily at midnight (UTC)
+- **Retention**: 2 days (configurable)
+- **Targets**: Test results, coverage reports, build outputs


This repository doesn’t currently include an “Artifact Cleanup” workflow; .github/workflows/cleanup.yml only deletes workflow runs. Please either add the referenced artifact-cleanup automation or adjust this subsection to match what exists.

Suggested change

#### Artifact Cleanup

Automatically removes old build artifacts:

- **Schedule**: Daily at midnight (UTC)

- **Retention**: 2 days (configurable)

- **Targets**: Test results, coverage reports, build outputs

#### Artifact Cleanup (optional)

This template does **not** include a dedicated artifact-cleanup workflow by default. If you want to automatically remove old build artifacts (such as test results, coverage reports, and build outputs), you can add a separate workflow (for example, `.github/workflows/artifact-cleanup.yml`) that:

- **Trigger**: Runs on a schedule (for example, daily at midnight UTC)

- **Retention**: Deletes artifacts older than a configurable number of days

- **Scope**: Targets large or short-lived artifacts to control storage costs

Copilot · 2026-01-22T22:07:29Z

docs/ci-cd.md

+| Trigger             | When              | Quality Gates       | Publish             |
+|---------------------|-------------------|---------------------|---------------------|
+| **Pull Request**    | PR opened/updated | ✅ All jobs run     | ❌ No               |
+| **Push to main**    | PR merged         | ✅ All jobs run     | ⚠️ Prerelease only  |


The “Push to main” row indicates prerelease publishing, but ci.yml does not publish on push (and only triggers on push when src/** changes). Publishing is done via the manual Release workflow.

Suggested change

| **Push to main** | PR merged | ✅ All jobs run | ⚠️ Prerelease only |

| **Push to main** | PR merged | ✅ All jobs run | ❌ No |

Copilot · 2026-01-22T22:07:30Z

docs/ci-cd.md

+# Adjust retention periods
+env:
+  ARTIFACT_RETENTION_DAYS: 7     # Keep artifacts for 7 days
+  MIN_RUNS_TO_KEEP: 5            # Keep at least 5 runs per workflow


The referenced cleanup.yml configuration snippet doesn’t match the actual workflow, which uses minimum-runs / retain-days inputs (and keep_minimum_runs / retain_days), not ARTIFACT_RETENTION_DAYS/MIN_RUNS_TO_KEEP. Please update this snippet to reflect the real options.

Suggested change

# Adjust retention periods

env:

ARTIFACT_RETENTION_DAYS: 7 # Keep artifacts for 7 days

MIN_RUNS_TO_KEEP: 5 # Keep at least 5 runs per workflow

# Adjust retention inputs and defaults

on:

workflow_dispatch:

inputs:

retain-days:

description: "Number of days to retain artifacts"

default: 7 # Keep artifacts for 7 days

required: true

minimum-runs:

description: "Minimum workflow runs to keep"

default: 5 # Keep at least 5 runs per workflow

required: true

env:

retain_days: ${{ inputs.retain-days }}

keep_minimum_runs: ${{ inputs.minimum-runs }}

Copilot · 2026-01-22T22:07:30Z

docs/development.md

+test-results/
+├── unit-tests.xml             # Pester test results (NUnit XML)
+├── code-coverage.xml          # Code coverage report (Cobertura)
+├── static-code-analysis.xml   # PSScriptAnalyzer results
+└── code-injection.xml         # InjectionHunter security scan


The documented test output filenames/formats don’t match the actual build/CI outputs. Invoke-UnitTests writes JaCoCo coverage to test-results/codecoverage/code-coverage.xml (and CI runs ReportGenerator on it), so code-coverage.xml (Cobertura) at the root of test-results/ is misleading.

Copilot · 2026-01-22T22:07:30Z

docs/development.md

+└── Get-Something.md               # One file per function
+
+build/out/YourModuleName/en-US/
+└── YourModuleName.dll-Help.xml   # MAML help for Get-Help


The generated external help filename here appears incorrect for this repo. The generated markdown files reference PSScriptModule-Help.xml (no .dll), and the build task exports MAML into build/out/<Module>/en-US/. Please update the example filename accordingly (e.g., <ModuleName>-Help.xml).

Suggested change

└── YourModuleName.dll-Help.xml # MAML help for Get-Help

└── YourModuleName-Help.xml # MAML help for Get-Help

Copilot · 2026-01-22T22:07:30Z

docs/ci-cd.md

+### Skipping Workflows
+
+For documentation-only changes, the workflow intelligently skips unnecessary jobs:
+
+```yaml


The docs say documentation-only changes “skip unnecessary jobs”, but PRs that touch docs/** still trigger ci.yml and run the reusable unit test/static analysis/security workflows (no conditional skip is implemented). Please update this section or implement the described skip logic.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Refactor documentation structure and content

89a2d79

marko-stanojevic requested a review from Copilot January 22, 2026 21:55

github-actions bot added feature docs labels Jan 22, 2026

Copilot started reviewing on behalf of marko-stanojevic January 22, 2026 21:55 View session

Copilot AI reviewed Jan 22, 2026

View reviewed changes

marko-stanojevic and others added 3 commits January 22, 2026 23:08

Update docs/getting-started.md

a1629a1

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/getting-started.md

a3f50ac

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/ci-cd.md

9a183b8

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

marko-stanojevic merged commit c7c0b51 into main Jan 22, 2026
1 check passed

marko-stanojevic deleted the feat/documentation_update branch January 22, 2026 22:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Refactor documentation structure and content #111

Refactor documentation structure and content #111

Uh oh!

marko-stanojevic commented Jan 22, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	\| Push to main \| PR merged \| ✅ All jobs run \| ⚠️ Prerelease only \|
	\| Push to main \| PR merged \| ✅ All jobs run \| ❌ No \|

-# Adjust retention periods
-env:
-  ARTIFACT_RETENTION_DAYS: 7     # Keep artifacts for 7 days
-  MIN_RUNS_TO_KEEP: 5            # Keep at least 5 runs per workflow
+# Adjust retention inputs and defaults
+on:
+  workflow_dispatch:
+    inputs:
+      retain-days:
+        description: "Number of days to retain artifacts"
+        default: 7            # Keep artifacts for 7 days
+        required: true
+      minimum-runs:
+        description: "Minimum workflow runs to keep"
+        default: 5            # Keep at least 5 runs per workflow
+        required: true
+env:
+  retain_days: ${{ inputs.retain-days }}
+  keep_minimum_runs: ${{ inputs.minimum-runs }}

	└── YourModuleName.dll-Help.xml # MAML help for Get-Help
	└── YourModuleName-Help.xml # MAML help for Get-Help

Uh oh!

Refactor documentation structure and content #111

Refactor documentation structure and content #111

Uh oh!

Conversation

marko-stanojevic commented Jan 22, 2026

Description

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants