Alarm aliases and redirect-only topics

The rule

Do not create a new topic when the only troubleshooting step is “follow this other guide.”

If the alarm should use the exact same troubleshooting flow as an existing topic, add the alarm to the existing topic’s alarms array instead. That array renders the Applicable alarms section on the page and is included in site search, so a reader who searches for any listed alarm should land on the canonical guide.

Redirect-only topics create extra search results, extra upkeep, and an extra click for the technician without adding any troubleshooting value.

What to do

Suppose you need to add support for 0x00100349 ZIP_EXECUTIVE_V4_C2_UNAVAILABLE, and that alarm should use the same troubleshooting steps as C2_EXTENDED_LOSS.

Do not create a new topic that only points to C2_EXTENDED_LOSS. Update the existing C2_EXTENDED_LOSS topic instead:

alarms: ["C2_EXTENDED_LOSS", "0x00100349", "ZIP_EXECUTIVE_V4_C2_UNAVAILABLE"],

List the hex value and the alarm constant separately when the reader may search either one. Keep the topic’s primary alarm first, then add the additional alarm identifiers after it.

Why this works

topic.alarms[] is used in three places:

• It renders the Applicable alarms chips on the topic page.
• It adds hidden weighted search text to the page, so the top-page search can find the topic by those alarm identifiers.
• It feeds the generated alarm coverage index used by the Alarm Lookup and coverage pages.

The generated alarm coverage index is rebuilt during local development and CI. Do not hand-edit site/src/data/alarm-coverage.json for this kind of change.

When to keep a separate topic

Keep a separate topic when the alarm has its own real troubleshooting content.

Examples:

• The steps differ from the existing guide.
• The alarm applies to different hardware or software versions in a way that changes what the reader should do.
• The alarm represents a different failure mode that needs its own troubleshooting flow.
• The page is a temporary workaround with unique mitigation steps, not just a pointer.
• The old topic has already been published and external links may rely on its URL. In that case, coordinate the cleanup instead of deleting it casually.

If you are only preserving a changed or deprecated alarm name for compatibility, check the existing redirect guidance and ask in #ask-troubleshooting-guide before adding an old alarm to a live topic.

Authoring checklist

Before creating a new alarm topic, ask whether the new alarm has its own troubleshooting flow.

1. If the same existing guide applies, add the new alarm identifiers to that guide’s alarms array.
2. If you already created a local redirect-only topic file, delete it before committing.
3. Link directly to the canonical topic from any related docs.
4. Let local build or CI rebuild the generated alarm coverage index.

The final result should be one guide, one canonical troubleshooting flow, and many searchable alarm identifiers that lead to it.