Skip to content
Zipline Zipline Service Documentation

    Guide content checklist

    Use this checklist after you create or edit a troubleshooting topic, and before you open or update the pull request.

    Quick checklist

    Section titled “Quick checklist”
    • Every path ends in one of the three workflow outcomes.
    • The rendered troubleshooting flow moves top-to-bottom in the UI.
    • No required information is missing or marked as a placeholder.
    • Links point only to controlled documents or controlled sources.
    • The topic has no guide-owner fields, Engineer Owner table, or Owner line.
    • The topic status is published.
    • Hardware labels are correct.
    • Applicable alarms are populated.

    One of three endings

    Section titled “One of three endings”

    Every path through the troubleshooting topic must end in one of the outcomes from Workflow outcomes:

    • Return to service.
    • Asset requires maintenance.
    • Escalate.

    Do not leave a branch with only a reference, a question, or a vague “check with engineering” instruction. The last step must tell the reader what happens next.

    Flow UI readability

    Section titled “Flow UI readability”

    Interactive troubleshooting guides must progress top-to-bottom in the UI. When a reader clicks Continue, Yes, or No, the next displayed box should appear below the box they just clicked from.

    Backward navigation can happen when multiple paths reuse an earlier step in the topic.steps[] array. The troubleshooting logic may be technically correct, but the rendered page feels broken because the reader has to look above their current position to find the next step.

    When this happens, preserve the reader’s path through the page. Duplicate or locally restate a shared action when needed so the visible flow keeps moving downward. User clarity is more important than avoiding every repeated step in an interactive troubleshooting flow.

    Use these rules when arranging topic.steps[]:

    • Design troubleshooting flows for readability first.
    • Avoid normal user paths that point back to earlier steps.
    • Duplicate shared actions when needed to preserve top-to-bottom flow.
    • Keep the troubleshooting logic and outcomes unchanged while improving navigation.
    • Test the rendered flow visually after refactoring.
    • Validate all next and options[].next references before merging.

    If the rendered flow does not read top-to-bottom, ask Codex to review and fix the flow before review. A useful prompt is: Review this topic for Flow UI readability. Keep the troubleshooting logic and outcomes unchanged, but restructure or duplicate steps so every normal reader path moves top-to-bottom in the rendered UI. Then validate every next and options[].next reference.

    If you fix it manually, preview the topic and click through each normal path. When a button sends the reader upward, duplicate or locally restate the shared step below the current step, then update the affected next or options[].next value to point to the new local step.

    No missing information

    Section titled “No missing information”

    Do not submit topics for review with missing content such as Content TBD, Placeholder for X, or incomplete notes. A published topic must be complete, correct, and ready for a Service Engineer or Maintenance Technician to follow.

    Section titled “Controlled links”

    Links in a troubleshooting topic must point to controlled documents or sources that readers are allowed to rely on operationally.

    Acceptable links include other service_docs troubleshooting topics or procedures, Baraza pages or templates, and maintenance manual sections. Do not link to Google Docs, Confluence pages, draft notes, or other uncontrolled source material from a published troubleshooting topic.

    If a Google Doc or Confluence page contains information the reader needs, move the relevant approved content into service_docs or a controlled document and link to that controlled location instead.

    Technical contacts

    Section titled “Technical contacts”

    Guides do not list an individual owner or SME. FSE and Engineering contacts are maintained in Technical Contacts by System. For a new guide, always use that table to find the FSE and assign the PR to them. The FSE completes this checklist before requesting human review.

    The initial draft can contain only the information available; this checklist applies when the guide is complete and ready for review.

    Status

    Section titled “Status”

    Confirm that the topic status is set to “published” before submitting the PR. Service Engineers and Maintenance Technicians are not allowed to follow instructions from a topic that is still marked as draft.

    Draft to published example
    status: "published",

    Hardware label

    Section titled “Hardware label”

    Add one or more hardware labels. Use all when the topic applies to every hardware version, or use the specific labels that match the affected hardware.

    Examples: all, EV2, EV3.

    Hardware label example
    hardware: ["EV3"],

    Alarms field populated

    Section titled “Alarms field populated”

    Add the alarms that route to the troubleshooting guide to the alarms field. If the field is empty, the guide may still be readable by title, but it will not be properly connected to alarm lookup, alarm coverage tracking, likely outcomes, or the Applicable alarms metadata shown in the UI.

    The rendered topic displays the alarm list as Applicable alarms.

    Related topic: Alarm aliases and redirects.

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