Documentation Assumptions and External Inspirations

Purpose

This page documents the assumptions we made while rewriting Matia documentation for clarity.
We intentionally did not change product or feature names. Instead, we:

• Reframed concepts in clearer terms.
• Reorganized pages into more guided flows.
• Borrowed successful patterns from leading data platforms.

Below, we list the main external docs we looked at and how they influenced our assumptions for each Matia product area.

---

ETL (Ingestion Pipelines)

Primary reference: Fivetran Getting Started docs
Examples:

• https://fivetran.com/docs/getting-started
• https://fivetran.com/docs/getting-started/quickstart

Observed patterns from Fivetran:

• Strong emphasis on quickstart flows that: sign up → connect source → connect destination → run first sync.
• Clear distinction between account / workspace setup and per-connector configuration.
• Consistent use of terms like connector, destination, sync, and free trial.

Assumptions applied to Matia ETL docs:

• A Matia ETL integration behaves similarly to a Fivetran connector:
  • One pipeline from a source asset to a destination asset.
  • Each run is a sync with its own status, volume, and run history.
• Users expect a first pipeline guide that:
  • Starts from the main Integrations list.
  • Walks step‑by‑step through: choose source → choose destination → configure → run first sync.
• Concepts like sync modes (full refresh, incremental, append‑only) and schema change handling are first introduced in a concept/overview and reinforced in how‑to guides.
• When we say emitted vs committed records, we mirror Fivetran’s pattern of surfacing both “read from source” and “written to destination” counts for transparency.

---

Reverse ETL (Activation)

Primary reference: Hightouch Docs
Example: https://hightouch.com/docs

Observed patterns from Hightouch:

• Reverse ETL is framed as activating warehouse data into operational tools.
• Strong emphasis on:
  • Models (SQL or semantic layer objects) as the definition of “who/what to sync”.
  • Sync modes like Mirror, Upsert, Update‑only.
  • Field mapping between warehouse columns and destination objects/fields.
• Clear breakdown of successful, rejected, and invalid records per sync.

Assumptions applied to Matia Reverse ETL docs:

• A Matia reverse ETL integration mirrors Hightouch-style pipelines:
  • Uses a model (SQL) to define the dataset.
  • Pushes changes into destination objects (e.g. Contact, Company).
• We treat:
  • Models as the primary abstraction for “what to sync”.
  • Destination objects and field mapping as the primary abstractions for “where it lands”.
• Sync modes in Matia (Mirror, Upsert, Update‑only / Delete‑only) are documented using terminology and behavior consistent with Hightouch, while keeping Matia’s naming.
• Per‑run metrics (successful, rejected, invalid records) are explained using the same mental model as Hightouch:
  • Rejected = destination refused the record (API/product rules).
  • Invalid = Matia validation failed before the record was sent (e.g. bad primary key).

---

Catalog and Lineage

Primary reference: Atlan Documentation
Examples:

• https://docs.atlan.com/
• https://docs.atlan.com/get-started/how-tos/quick-start-for-admins
• https://docs.atlan.com/get-started/how-tos/quick-start-for-data-consumers
• https://docs.atlan.com/product/capabilities/discovery/how-tos/search-and-discover-assets

Observed patterns from Atlan:

• Strong role‑based framing (admins, contributors, data consumers).
• Catalog pages focus on:
  • Discovery (search, filters, asset types).
  • Asset profiles with rich context (owners, tags, classifications, popularity).
  • Glossary terms, certifications, and announcements for governance.
• Features like search everywhere (Cmd/Ctrl+K), starred assets, and recently viewed are used to make navigation easier.

Assumptions applied to Matia Catalog docs:

• Matia has a catalog homepage and asset tree that act similarly to Atlan’s discovery experience:
  • Browse by type (warehouse, schema, table, BI, orchestration).
  • Search and filter as primary discovery mechanisms.
• Certificates (Verified, Draft, Deprecated) and announcements on assets map conceptually to Atlan’s certifications and warnings:
  • We assumed they are the primary way to express quality and guidance to end users.
• Tags, owners, and other metadata work similarly to Atlan:
  • They drive search, filtering, and context on asset pages.
• We introduced clearer flows like “Discover and certify an asset” with explicit steps (open catalog → browse → open asset → apply certificate), modeled after Atlan’s task‑based “search and discover assets” guides.

---

Observability (Monitors, Data Quality)

Primary reference: Monte Carlo Docs
Example: https://docs.getmontecarlo.com/

Observed patterns from Monte Carlo:

• Observability is framed around:
  • Monitors for freshness, volume, schema, and custom rules.
  • Incidents / Issues when monitors fail.
  • Workflows to detect → triage → resolve data problems.
• Distinction between auto‑generated / default checks and custom monitors.
• Clear explanation of monitor status states and lifecycle (healthy, alerting, training, disabled, error).

Assumptions applied to Matia Observability docs:

• A Matia monitor behaves similarly to a Monte Carlo monitor:
  • It runs a query (or metadata check), logs results over time, and compares them against expectations.
  • Results feed an issue/alerting workflow.
• We framed Matia observability around:
  • Auto‑generated monitors (freshness + row count per table for selected schemas).
  • Custom monitors (SQL and standard types like cardinality, nullness, uniqueness).
• We assumed Matia uses a similar status model:
  • Healthy, Alerting, Training, Error (and we explained each explicitly).
• The “first monitors” and “add custom monitor” guides were structured as task‑based workflows, similar to Monte Carlo’s “Monitors Overview” and “Get Started” patterns.

---

Cross‑Cutting Documentation Patterns

Across all competitor docs, we saw several patterns that we adopted in Matia docs:

• Task‑based guides instead of feature dumps:
  • “Create your first integration”, “Discover and certify an asset”, “Create your first monitors”, etc.
• Clear sections for:
  • Who this is for (personas/roles).
  • What you’ll accomplish by the end of the page.
  • Before you begin (prerequisites like permissions and connections).
  • Step‑by‑step flows with numbered steps.
  • Next steps that link to deeper concepts and references.
• Consistent terminology within each product area while preserving Matia’s feature names.
• Explanations that highlight:
  • How features work together (e.g. Catalog + Observability + Integrations + Lineage).
  • How users should interpret metrics and statuses (e.g. emitted vs committed records, successful vs rejected vs invalid records, healthy vs alerting vs training monitors).

We used these patterns liberally to make Matia documentation substantially clearer and more approachable, without changing any underlying product semantics or feature names.