Guide authoring workflow checklist

Use this checklist after you have worked through the Beginner’s Guide once and want a shorter path from branch setup to review.

This is not a replacement for the full training. If a step feels confusing, go back to the linked section for the full explanation.

Before you edit

• Open the service_docs repo in VS Code.

• Open the Codex chat panel.

• Start the local preview, or plan to start it before you review the page. For the full steps, see Start the local preview.

• Ask Codex to check your branch and working tree before editing:

  I want to work on a service_docs topic.
  Please check the current git status and branch.
  If the working tree is clean, switch to main, pull the latest origin/main with --ff-only, and create a new branch named [your-name/short-description].
  If there are uncommitted changes, stop and explain what files are changed before doing anything else.
  Do not edit documentation yet.

Author the topic

• Tell Codex what you want to create or update in plain English.
• Give Codex the technical source material: alarm names, screenshots, notes, expected actions, and the documented escalation path.
• Ask Codex to inspect nearby topics before editing.
• Review the rendered topic in the local preview.
• Ask Codex to fix anything that looks wrong in the browser.
• For an existing-guide edit, verify your proposed change. For a new guide, draft with the information available; the assigned FSE completes and verifies the guide before human review.

For prompt examples, see Author with Codex.

Prepare the pull request

• When the local preview looks right, ask Codex:

  The local preview looks good. Please prepare this change for review.
  
  First show me the files that changed and summarize the change in plain English.
  Run the appropriate checks for this service_docs change.
  If the checks pass, commit the change and push this branch to origin.
  Then prepare a pull-request title and body using the repo's PR template.
  Do not create the pull request until I approve the title and body.

• Review the changed file list, summary, checks, PR title, and PR body.

• Approve the title and body only if they match the change.

For the full version, see Prepare the pull request.

New guide: open a PR and hand it to the FSE

1. Open ZiplineTeam/service_docs, click Compare & pull request, and confirm that the base is main.
2. Paste the approved title and body, then choose Create pull request.
3. Always use Technical Contacts by System to find the relevant FSE and select them in Assignees. Assignment is manual.
4. The FSE reviews and revises the draft on the same branch, completes service and maintenance guidance, and coordinates additional technical input.
5. The FSE completes the Guide content checklist and PR readiness checklist, then moves the PR to Waiting for TW Review.
6. The FSE coordinates TW/SE2 review, requested updates, and merge. Follow PR workflow.

Existing guide: open the PR and follow through

1. Open GitHub, click Compare & pull request, confirm the base is main, and paste the approved title and body.
2. Click Create pull request and assign yourself manually.
3. Check CI and address failures and automated-review findings.
4. Complete the PR readiness checklist.
5. Follow the review path for your role on Guide ownership and workflow and update the PR’s review status.
6. Address requested changes, push updates, and return the PR to the applicable review status.

Merge the pull request

The assigned FSE completes the merge for a new guide; the author completes it for an existing-guide edit. Both use the existing TW/SE2 review process. Auto-merge can be enabled separately for that PR, or the responsible person can merge manually at Ready to Merge.

For instructions, see Auto-merge PR.