Write a help article technicians can use

The toolkit already creates the technical part of every module article: type, target support, risk, confirmation, parameters, permissions, timeout, version, and step-by-step launch instructions.

Your HELP.md should answer the questions the manifest cannot:

1. When should I use this tool?
2. What evidence does it inspect?
3. What do the common results mean?
4. What can it miss?
5. What is the safest next step?

If a technician can answer those five questions after reading the article, it is doing its job.

Add an article in three steps

1. Create HELP.md

Place it beside module.json and the entry-point script.

product-health/
|-- module.json
|-- main.ps1
`-- HELP.md

2. Declare it in the manifest

"help_file": "HELP.md"

The filename must end in .md and cannot contain a directory path. If a declared file is missing, the module is rejected during discovery so broken documentation is visible immediately.

If help_file is omitted, the application looks for HELP.md and then README.md. If neither exists, the generated baseline article is still available. Modules using the explicit field require application version 0.22.0 or newer.

3. Use the template below

Replace every instruction with real product knowledge. Delete sections that truly do not apply.

# Product Health

## When to use this module

Use this module when the user reports ...

## What it checks

- Checks ...
- Reads ...
- Compares ...

## How to interpret the results

- **Passed:** Explain what was confirmed.
- **Warning:** Explain the likely condition and what should be validated next.
- **Failed:** Explain whether the tool confirmed a problem or could not complete a critical check.
- **Informational:** Explain why this context matters even though it is not a failure.

## Limitations

- Explain remote-session or interactive-user limitations.
- List product versions or permissions that affect visibility.
- Describe known ambiguous results without pretending they are certain.

## Recommended next steps

Describe safe validation first. Point to a separate confirmed action when a repair is appropriate.

Prefer concrete language

Weak:

Checks the service and returns useful data.

Better:

Confirms that the Print Spooler is installed and running, counts configured queues, and identifies jobs that have remained in an error state. It does not clear the queue or restart the service.

Weak:

Fix the issue and try again.

Better:

Confirm the device is on the corporate network, then rerun the DNS consistency diagnostic. If the mismatch remains, use the approved DNS registration action and verify forward and reverse lookup.

Use short paragraphs, descriptive headings, and lists. Put one idea in each sentence. Define uncommon abbreviations the first time they appear.

Write for the person using the result

• Use the same test and parameter names that appear in the UI.
• Explain where evidence comes from: target, controller, interactive user, or remoting identity.
• State clearly whether the module changes anything.
• Describe access limitations as normal evidence, not mysterious failure.
• Never include credentials, tokens, real user data, or real device data in examples.
• Keep recommendations deterministic and qualify uncertain correlations with words such as may.
• Update help whenever behavior, parameters, permissions, risks, or target support changes.

Make the article easy to find

Help search includes the module name, ID, category, type, tags, generated sections, and HELP.md. Include the words technicians actually use: product name, common abbreviation, Windows component, and reported symptom. Do not stuff a hidden keyword list into the article; use the terms naturally.

Final review

• ☐ A new technician can tell when to use the module.
• ☐ Every important warning or failure has an explanation.
• ☐ Remote and interactive-session limitations are explicit.
• ☐ Recommendations begin with safe validation.
• ☐ Examples contain no real organization data or secrets.
• ☐ Search finds the article by product and symptom.
• ☐ The article renders correctly in light and dark themes.
• ☐ module.json, HELP.md, and the entry point ship in the same folder.

The copyable examples under repository-examples\modules include a short HELP.md for every module type. Start with the closest example and replace its teaching text with your module’s real behavior.