Skip to content
Zipline Zipline Service Documentation

    Author Guide

    This guide is for authors who create or update service_docs troubleshooting topics.

    Use it after you understand the basic GitHub/Codex workflow and need the service_docs-specific rules: topic structure, troubleshooting flow, hardware and software applicability, review workflow, and automated checks.

    If GitHub, Markdown, VS Code, Codex, branches, pull requests, or local preview are new to you, start with Beginner’s Guide to Authoring Topics with Codex first.

    Main path

    Section titled “Main path”
    1. Know your audience - who reads troubleshooting topics, where they use them, and what belongs in a topic.
    2. Author responsibilities - responsibilities for initiating a new guide or editing an existing guide.
    3. Topic structure - frontmatter, the topic object, the wrapper, and prose.
    4. Writing the troubleshooting flow - step types, next, options[].next, notes, and rendered flow.
    5. Workflow outcomes - every branch ends in return to service, asset requires maintenance, or escalate.
    6. Software and hardware applicability - use softwareVersions and hardware only when they change what the reader should do.
    7. Automated checks and review signals - CI, AI Content Review, Greptile, Confidence Score, and when to ask for help.

    References and appendices

    Section titled “References and appendices”

    Checklists

    Section titled “Checklists”