Create a New Guide

Use this workflow when you intend to author and submit a new troubleshooting guide. If you only want to request a guide for someone else to author, use New Topics and General Requests.

Before You Start

Search the Alarm Lookup and the site to confirm that a guide or equivalent troubleshooting flow does not already exist.
Check All Open Pull Requests to see whether someone is already adding the guide.

New to editing content? Start with the Beginner’s Guide to set up your workspace and work through your first documentation change.

Choose How to Author

With Codex or zdex

If you are new to editing repository content, the Codex workflow can handle the file and Git mechanics while you review and verify the change.

Use plain English to provide the source material and describe the required troubleshooting flow. Ask the AI assistant to inspect existing topics in the likely category, follow repository conventions, stop when technical information is missing, and run the required checks.

Start with the Beginner’s Guide to Authoring Topics with Codex or Use zdex from Slack. The Codex prompt reference contains a detailed new-topic prompt.

Codex can handle repository mechanics and draft the structure. Provide accurate initial information, preserve safety wording and documented escalation routing, and identify missing details without inventing them. The assigned FSE completes the guidance and coordinates technical input before human review.

Without Codex

Create a branch from the latest main, inspect a nearby topic with a similar flow, and add the new file in the appropriate content directory. Use the Author Guide for topic structure, step types, outcomes, and applicability rules.

Preview the rendered guide locally while you work. Do not rely only on the MDX source.

Open a PR and assign the FSE

Create a PR with the information available. Always use Technical Contacts by System to find the relevant FSE, then select them manually in the PR’s Assignees field. Creating the initial draft does not make you responsible for completing every part of the guide.

The FSE reviews and revises the guide on the same PR branch, completes the troubleshooting and service and maintenance guidance, and coordinates any additional technical input. Guidance should link to controlled maintenance procedures rather than recreate them.

When the content is ready, the FSE reviews the rendered guide, tests its paths, completes the Guide content checklist and PR readiness checklist, then moves the PR to Waiting for TW Review. The FSE then coordinates the existing TW/SE2 review process and completes the merge.

Required approvals remain TW/SE2. FSE assignment does not add a separate approval requirement. After publication, Service Engineering collectively maintains operational content under TW oversight. For the full workflow and role table, see Guide ownership and workflow.

Access Required

You need a Zipline GitHub account and write access to ZiplineTeam/service_docs. See Check GitHub Access if you need access.

Open suggestions

There are no open suggestions.

Open pull requests

There are no open pull requests.