Skip to content
Zipline Zipline Service Documentation

    Guide ownership and workflow

    Once a guide is published, the Service Engineering team collectively owns its operational content and upkeep, with Technical Writer oversight and accountability for the published deliverable. FSEs and software/hardware engineers provide technical expertise when needed.

    For new guides, authors create a PR with the information available and assign it to the relevant FSE listed on Technical Contacts by System. The FSE completes the guide, coordinates any additional technical input, and takes the PR through review and merge. Creating the initial draft does not make you responsible for completing every part of the guide.

    For existing guides, authors make the proposed edits and take the PR through review and merge. They may consult FSE or Engineering expertise when needed; additional technical review is optional.

    For both new and existing guides, TW and SE2 complete required reviews and may make nontechnical editorial fixes as needed.

    See PR workflow for review paths and handoffs, and How to review a PR for detailed instructions.

    Who owns what

    Section titled “Who owns what”
    Role Accountability / focus Expected contribution
    Service Engineer (SE/SE2) Shared ownership of operational content and upkeep. Drive improvements and suggestions; integrate cross-team input; validate operational usability; assign and resolve suggestions.
    Technical Writer (TW) Accountability for the documentation deliverable and TW oversight. Maintain documentation quality and consistency; provide required TW review; make nontechnical editorial fixes.
    Field Systems Engineer (FSE) Service, maintenance, and system/subsystem expertise; responsibility for completing assigned new guides and coordinating their review. Review and revise the initial draft on the same PR branch; complete service and maintenance guidance; coordinate additional technical input; take the PR through the existing TW/SE review process and merge. Provide expertise for existing-guide updates when needed.
    Software / Hardware Design Engineer (SME) Technical accuracy in their domains; initial drafting and technical input for new guides. When initiating a new guide, create a PR with the information available and assign it to the relevant FSE. Provide technical clarification and input as needed; engage on design-change requests. Routine guide upkeep stays with SE.

    Workflow

    Section titled “Workflow”

    Learn about the workflow for new and existing guides.

    Ownership examples

    Section titled “Ownership examples”
    A Baraza template for alarms/errors already in a guide

    SE can create a Baraza template and update the guide to improve the troubleshooting workflow when the relevant alarms/errors and meaning are already known. If an alarm/error is missing or unclear, ask the relevant engineer to identify or explain it, then have SE drive the PR. If the guide also contains ambiguous team escalation guidance, SE coordinates with the relevant team to clarify that part. The engineer answering a firmware question does not thereby inherit all cleanup and coordination for the page.

    Guides with multiple teams ownership

    Sometimes a guide contains triaging that can branch to more than one team. Example, triaging between a battery issue or an autonomy issue. If there is any suggestion to reduce/improve escalation to the autonomy team, the SE coordinates with the relevant team to clarify that part. The SME on the battery side does not thereby inherit all cleanup and coordination for the page.

    An unresponsive compute with several possible causes

    For updates to an existing unresponsive compute guide, SE coordinates the guide’s operational workflow and uses the relevant FSE, firmware, embedded linux, and electrical contacts to answer specific questions. Firmware expertise may explain power behavior; embedded linux may explain compute software behavior; electrical/FSE expertise informs inspection and maintenance actions. SE integrates those inputs into usable triage guidance. This preserves the original example’s cross-domain intent while using the later agreed shared-SE model instead of assigning one guide owner.

    A battery-health guide or a new alarm

    For a new guide covering battery health or a new alarm/error, you create a PR with the information available and assign it to the relevant FSE as listed on the Technical Contacts by System page. The FSE completes the troubleshooting and maintenance guidance, gathers input from firmware and battery-hardware experts as needed, and coordinates the PR through the existing TW/SE review process. After publication, SE collectively maintains the operational content and consults those experts when needed. Design teams remain responsible for accurate technical input and engagement with requests for design changes.

    A small technical edit that exposes broader cleanup

    An SME may make a small change to technical content, during which a review of the PR/guide makes TW/SE realize there is other cleanup that could be done on the guide. TW/SE may make nontechnical editorial fixes directly; broader operational cleanup can be taken up by SE through the normal process. The SME is not responsible for inheriting general cleanup unrelated to technical contributions.

    Change requests

    Section titled “Change requests”

    Suggestions are a shared SE2 team responsibility, with FSE and Engineering input as needed, rather than being auto-assigned to individual SMEs. For more information about suggestions, see Suggest a Change.