Skip to main content

PLAYBOOK

ZAYAZ Documentation & Delivery Playbook

Purpose​

This playbook defines clear rules, responsibilities, and lifecycle boundaries between Docusaurus Docs, Jira, and Confluence. Its goal is to:

  • Keep the ZAYAZ Manual authoritative and trusted
  • Enable fast, flexible delivery without losing knowledge
  • Power Ask ZARA with reliable, structured context for internal understanding, maintenance, and advanced technical support

The Golden Rule (Non‑Negotiable)​

Docusaurus Docs are the system of record.

Everything else (Jira, Confluence, chat, meetings) may inform the system — but must never replace it.

If information matters long‑term, it must live in Docs.

System Roles & Responsibilities​

1. Docusaurus Docs — Stable Truth​

What belongs here

  • Concepts, architecture, invariants
  • Business rules, contracts, guarantees
  • Examples that define expected behavior
  • Glossaries, IDs, schemas, naming conventions
  • Decisions that must remain true over time

What must NOT live here

  • Sprint‑specific implementation details
  • Temporary workarounds
  • Meeting notes
  • Experimental approaches

Rules

  • Every Doc page has a stable id
  • Every actionable requirement is tagged with <JiraNeed type="Task" needId="playbook#1-docusaurus-docs-stable-truth#1" jiraKey="ZYZ-666" />
  • Docs are written to be read without Jira or Confluence
  • If a Confluence/Jira item contradicts Docs → Docs win

Ask ZARA role

  • Primary knowledge source
  • Canonical answers
  • Long‑term system understanding

2. Jira — Execution & Traceability​

What belongs here

  • Work items (Epics, Stories, Tasks, Bugs, Validation)
  • Status, assignee, sprint, priority
  • Acceptance criteria
  • Links back to Docs sections

What must NOT live here

  • Full system explanations
  • Architecture narratives
  • Long‑form reasoning

Rules

  • Every Jira issue must link back to:

    • A Spec ID
    • A Doc section (when applicable)

  • Jira descriptions are contextual, not exhaustive

  • Jira is disposable once work is done — Docs are not

Ask ZARA role

  • Status awareness
  • "What is being worked on / blocked / done"
  • Operational visibility

3. Confluence — Evolving Engineering Narrative​

What belongs here

  • Implementation approaches
  • Trade‑off discussions
  • ADR drafts (before promotion)
  • Spike outcomes
  • Meeting notes
  • Diagrams in flux

What must NOT live here

  • Final architecture decisions
  • Long‑term contracts
  • Anything that must be correct in 6 months

Rules

  • Confluence content is temporary by default

  • Every Confluence page must answer:

    • "What Doc does this relate to?"

  • When something stabilizes → it must be promoted to Docs

Ask ZARA role

  • Secondary / supporting context
  • "Why was this done this way?"
  • Historical reasoning

Lifecycle of Knowledge (Required Flow)​

  1. Idea / Discussion

    • Lives in meetings, chat, Confluence

  2. Decision Draft

    • Lives in Confluence
    • Linked from Jira

  3. Execution

    • Lives in Jira
    • Traced back to Docs

  4. Stabilization

    • Promoted to Docusaurus Docs
    • Jira closed

  5. Archive

    • Confluence remains as history
    • Docs become the truth

❗ If step 4 never happens → technical debt is created.

Promotion Rules (Critical)​

A Confluence item must be promoted to Docs when:

  • It affects external behavior
  • It introduces a new contract or invariant
  • It resolves a design debate
  • It would break things if misunderstood later

Promotion means:

  • Rewriting in Docs language
  • Removing temporary wording
  • Adding examples where relevant
  • Tagging with <JiraNeed type="Task" needId="playbook#promotion-rules-critical#1" jiraKey="ZYZ-665" /> if actionable

Ask ZARA Strategy​

Trust Hierarchy (for answers)​

  1. Docusaurus Docs (highest trust)
  2. Jira (status & execution facts)
  3. Confluence (context, reasoning)

Response Behavior​

  • ZARA should prefer Docs when conflicts exist

  • ZARA may cite Jira/Confluence with timestamps

  • ZARA should clearly label source:

    • "According to the ZAYAZ Manual…"
    • "According to Jira issue ZYZ‑123…"

Indexing Policy (Future‑proof)​

  • Docs: full‑text indexed

  • Jira: summary + description + metadata

  • Confluence: full‑text OR link‑only (configurable)

  • All indexed content includes:

    • source
    • specId
    • updatedAt

Anti‑Patterns (Explicitly Forbidden)​

🚫 "The real spec is in Confluence"

🚫 "Just check the Jira description"

🚫 "It was decided in a meeting"

🚫 Long‑term knowledge living only in comments

If someone says any of the above → the system is drifting.

Roles & Accountability​

Documentation Owner​

  • Guards Docs integrity
  • Approves promotions from Confluence

Program Manager​

  • Uses Docs + Jira to plan work
  • Never redefines specs in Jira

Engineers​

  • Use Confluence for exploration
  • Promote outcomes back to Docs

Ask ZARA​

  • Enforces consistency
  • Surfaces contradictions
  • Highlights outdated content

North Star Principle​

Docs are not documentation.

Docs are the system itself — expressed in language.

Everything else exists to serve that system.

📘 Documentation Governance​

Request for Change (RFC) & Approval Flow​

Purpose

This section is the authoritative definition of how documentation changes are proposed, reviewed, and approved.

To ensure that the ZAYAZ Manual remains a stable, trusted source of truth, all changes to documentation follow a formal Request for Change (RFC) process. This guarantees quality, traceability, and long-term maintainability.

🔒 Principle​

Documentation changes are reviewed, approved, and audited — never edited ad hoc.

🧭 Roles & Responsibilities​

RoleResponsibility
RequesterProposes a documentation change via RFC
Reviewer / OwnerEvaluates, approves, or rejects the change
Manual MaintainerApplies approved changes to the documentation
Ask ZARA / SearchIndexes only approved, merged documentation

🔄 RFC Workflow (End-to-End)​

  1. Change Request Submission

Documentation changes are requested using the Request for Change (RFC) function available in the manual.

The RFC:

  • Is submitted by internal or authorized external users
  • Automatically creates a ticket in HubSpot
  • Includes context, rationale, and affected documentation sections
  1. Review & Decision (HubSpot)

Each RFC ticket is reviewed by the designated documentation owner.

Possible outcomes:

  • ✅ Approved — change is authorized
  • ❌ Rejected — change is declined with rationale
  • 🔄 Clarification Requested — requester must provide more detail

All decisions are logged in HubSpot for traceability.

  1. Manual Update (Controlled Edit)

Approved RFCs are implemented as explicit documentation changes:

  • Versioned
  • Traceable
  • Attributable to an approved RFC

No direct edits bypass this process.

  1. System Propagation

Once merged:

  • The manual is rebuilt
  • Search indices are regenerated
  • Ask ZARA ingests the updated content
  • Jira traceability remains intact

Only approved content becomes discoverable or answerable.

🔗 Relationship to Other Systems​

SystemRole
ZAYAZ ManualStable, approved system truth
HubSpot (RFCs)Change governance & audit trail
JiraExecution tracking linked to documentation
ConfluenceOptional evolving engineering narrative
Ask ZARATrusted retrieval over approved knowledge

🧠 Why This Matters​

This RFC model ensures that:

  • ❌ Experimental or half-finished ideas never pollute the manual
  • ✅ Knowledge quality improves over time
  • 🔍 Every change has an owner, reason, and history
  • 🤖 Ask ZARA only answers from validated knowledge
  • 🛡️ Future teams inherit a governed system, not tribal memory

🧩 Key Rule (Non-Negotiable)​

If it’s not approved via RFC, it does not exist in the Manual.

RFC Lifecycle — Manual as Source of Truth​

🔮 Hecate Signals (Governance Awareness)​

What Are Hecate Signals?​

Hecate Signals are governance and integrity warnings surfaced by Ask ZARA when the ZAYAZ knowledge system may be drifting away from its own rules.

They are signals, not errors. They do not block work, enforce changes, or override human judgment.

Hecate exists to make drift visible early.

⸻

What Hecate Monitors​

Hecate evaluates relationships between systems, not raw content.

It observes:

  • Docusaurus Docs (system of record)
  • Jira issues and epics (execution)
  • Confluence content (evolving narrative)
  • RFC metadata in HubSpot (change governance)

Hecate does not decide correctness — it detects misalignment.

Signal Categories​

Hecate surfaces four primary signal types:

  1. Source-of-Truth Signals (Highest Importance) Raised when Jira or Confluence appears to contradict documented behavior or contracts.

Docs always take precedence.

  1. Traceability Signals Raised when execution exists without a clear link back to Docs.

Examples:

  • Jira issue missing Spec ID
  • <JiraNeed type="Task" needId="playbook#signal-categories#1" jiraKey="ZYZ-667" /> without a linked Jira issue
  • Epic exists without child issues
  1. Freshness & Drift Signals Raised when stabilized execution is not reflected in Docs.

Examples:

  • Jira marked Done but Docs unchanged
  • RFC marked Published but no documentation update
  1. Governance Process Signals Raised when documentation changes may have bypassed the RFC process.

Examples:

  • Doc updated without an approved RFC
  • Approved RFC not yet reflected in Docs

Severity Levels​

Hecate uses graduated severity levels to avoid alert fatigue.

LevelMeaning
P0Governance broken (hard violation)
P1High risk of wasted or invalid work
P2Growing entropy or drift
P3Hygiene / quality signal
P4Informational insight

Only P0–P2 represent violations. P3–P4 are advisory system health signals.

How Signals Are Shown​

Hecate signals may appear as:

  • Trust notices in Ask ZARA responses
  • Governance dashboards (e.g. /system/violations)
  • Slack or email alerts for high-severity cases (P0–P1)

Hecate never edits content or assigns blame.

Key Rule (Non-Negotiable)​

Hecate flags. Humans decide. Docs remain authoritative.

For full details on how signals are generated and classified, see: → ZARA’s Hecate — Governance & Drift Detection.



GitHub RepoRequest for Change (RFC)