Skip to content

Improve command discoverability: a selection matrix doc + -Help summary for the ScubaGear module聽#2433

Description

@DickTracyII

Prerequisites

  • This issue has an informative and human-readable title.
  • Assignee should meet with issue author before starting work.

馃挕 Summary

ScubaGear now exports a growing set of user-facing commands (Invoke-SCuBA, Invoke-SCuBACached, Invoke-SCuBADiff, New-SCuBAConfig, Start-SCuBAConfigApp, Start-SCuBAConfigAnalyzer, Show-SCuBABaselinePolicyViewer, plus setup/dependency commands). New and returning users struggle to know which command to use, when, and why without reading several long docs. This issue adds two low-cost, high-value discoverability aids:

  1. A tool-selection matrix page in docs/: a one-screen cheat sheet mapping each command to a BLUF, "use it when," and "why it matters."
  2. A -Help summary surfaced from the module itself so users get the same at-a-glance guidance directly in the terminal, without leaving PowerShell.

Motivation and context

  • The command surface keeps expanding; existing docs are thorough but require a lot of reading to answer "which one do I run?"
  • Users often discover commands by accident or word-of-mouth, then reach for the wrong tool (e.g., re-scanning when Invoke-SCuBACached or Invoke-SCuBADiff would do).
  • A concise decision aid - in docs and in-terminal - shortens time-to-first-success and reduces support questions.

Implementation notes

Docs (partially drafted)

  • docs/misc/tool-selection-matrix.md with two matrices:
    • Configuration & analysis tools (New-SCuBAConfig, Start-SCuBAConfigApp, Start-SCuBAConfigAnalyzer, Show-SCuBABaselinePolicyViewer, Invoke-SCuBADiff).
    • Core assessment commands (Invoke-SCuBA, Invoke-SCuBACached, Disconnect-SCuBATenant, Install-ScubaDependencies, Install-OPAforSCuBA, Get-ScubaGearDependencyStatus, Update-ScubaGear).
    • Include a Mermaid flow showing how the tools chain together.
  • Link the page from README.md (Configuration & Usage + Additional Resources).

In-terminal help

  • Add a lightweight help summary command, e.g. Get-ScubaHelp (verb-approved) that prints the same matrix content as a formatted table grouped by category, with a one-line BLUF per command and a pointer to the docs page.
  • Consider a -Help switch on Invoke-SCuBA that routes to the same summary, since Invoke-SCuBA is the most common entry point and where users land first.
  • Source the summary from a single data structure (hashtable/JSON) so the docs matrix and the in-terminal output can be generated/validated from one source of truth and won't drift.
  • Keep it dependency-free and offline; no Graph/tenant calls.
  • Export the new command in ScubaGear.psd1 (FunctionsToExport) and add a comment-based help block.

Acceptance criteria

  • docs/misc/tool-selection-matrix.md exists with both matrices (BLUF / when / why) and a Mermaid diagram.
  • README.md links to the new matrix page in at least one discoverable location.
  • A terminal help summary is available (Get-ScubaHelp and/or Invoke-SCuBA -Help) that lists each user-facing command with a one-line BLUF, grouped by category, and points to the docs page.
  • The help command runs fully offline with no tenant/Graph calls and no errors on a clean install.
  • The new command is exported in ScubaGear.psd1 and has comment-based help.
  • In-terminal summary and docs matrix stay consistent (ideally generated/validated from a single source).
  • Unit test(s) cover the help command output (e.g., every exported user-facing command appears in the summary).
  • Docs and any new command follow the repo CONTENTSTYLEGUIDE.md and pass PSScriptAnalyzer.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementThis issue or pull request will add new or improve existing functionality

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions