Skip to content

A Guide for Reviewers

This documentation is engineered to serve two key audiences: the strategic leader who needs to understand the "why," and the technical builder who needs to master the "how." Our goal is to provide a clear, authoritative guide to the Arkham platform, balancing high-level vision with deep technical detail.

This document explains the philosophy and structure we use to achieve that goal.

Our Audience: The Guider and The Builder

We write for two primary personas:

  • The Guiding Champion (The "Why"): This is a business or technology leader (e.g., CTO, Head of Transformation). They need to understand how Arkham solves critical business problems and enables new operational capabilities. They care about the strategic value, the speed of implementation, and the governance framework.
  • The Technical Champion (The "How"): This is the hands-on expert (e.g., Data Engineer, ML Scientist, Data Architect). They need to understand how to build on, integrate with, and deploy solutions using the Arkham platform. They require clear, detailed, and technically accurate information.

Our documentation is structured to meet the needs of both personas, often on the same page.

Our Core Value Propositions

Three core value propositions drive the architecture of our platform and our documentation.

  1. A Unified Data Foundation: We believe that transformative AI begins with trusted data. Our platform is engineered to unify an organization's fragmented data landscape into a single, reliable source of truth, creating a stable foundation for all analytics and AI.
  2. Vertically Integrated AI, from Analytics to Action: Arkham is more than a collection of tools; it's a vertically integrated system for operational AI. This is most powerfully demonstrated by TARS, our proactive AI copilot. TARS leverages the Ontology—a digital twin of your business—to not only accelerate development and surface insights in dashboards but to help orchestrate and automate core operational decisions.
  3. Governance that Enables Speed: We build governance into the fabric of the platform. This provides the security and auditability that enterprises require, but we frame it as an enabler of speed. By providing clear guardrails, we empower builders to innovate with confidence.

Our Documentation Structure

To serve our dual audience, we employ a clear, hierarchical structure.

  • Overview Pages (/capabilities/[capability]/overview.md): These pages are designed for a top-down understanding. They begin with a high-level, strategic vision to engage the Guiding Champion, then provide the conceptual pillars and component overviews for the Technical Champion. They culminate in a "Builder's Journey" user story, which provides a memorable, practical example for all audiences.
  • Component Pages (/capabilities/[capability]/[component].md): These pages contain the deep, systematic decomposition of each specific tool (e.g., Connectors, Pipeline Builder). This is where the Technical Champion will find detailed explanations of features, benefits, and workflows.

This structure allows readers to engage at the level of detail they require, moving seamlessly from strategic vision to hands-on implementation.

The Anatomy of an Overview Page

All of our overview.md pages follow a deliberate, top-down structure. Each section is designed to answer a specific question for the reader, guiding them from the strategic "why" to the practical "how."

  • 1. Vision Statement (# Title)

    • Purpose: To hook the reader by framing a critical industry problem and immediately positioning Arkham as the definitive solution.
    • Audience: Engages the Guiding Champion by speaking to their strategic challenges.

  • 2. Pillars / Framework / Purpose (## Pillars of...)

    • Purpose: To provide a concise, high-level summary of the capability's core principles. This section establishes the conceptual foundation of our solution.
    • Audience: Gives the Guiding Champion a memorable framework and provides the Technical Champion with the foundational concepts.

  • 3. Core Components (## Core Components)

    • Purpose: To act as the primary navigational hub for the capability. This section lists the individual tools that make up the capability and directs users to the detailed component pages.
    • Audience: Primarily serves the Technical Champion who is looking for the systematic decomposition of features.

  • 4. Core Concepts (## Core Concepts)

    • Purpose: To provide a quick, scannable glossary of the key vocabulary associated with the capability. This ensures a shared language and clarifies terminology.
    • Audience: A helpful reference for both personas.

  • 5. Builder's Journey (## The Builder's Journey...)

    • Purpose: To serve as a contextual culmination that synthesizes all the preceding concepts into a single, narrative workflow. The journey makes the abstract concepts tangible and demonstrates the integrated power of the platform.
    • Audience: Provides a powerful, memorable example for all audiences, showing the platform in action.

The Anatomy of a Component Page

Mostly, component pages are where we provide the deep, systematic decomposition of a specific tool for the Technical Champion. While the structure is more flexible than an overview.md page to accommodate the unique nature of each tool, most component pages follow a similar pattern designed for clarity and technical depth.

  • 1. Title & Introduction

    • Purpose: To frame a common industry problem and introduce the specific Arkham component as the engineered solution.
    • Example: docs/capabilities/data-platform/pipeline-builder.md

  • 2. "How It Works" Section

    • Purpose: This is the core of the page, explaining the component's architecture and primary workflow. It often uses a Mermaid diagram, a screenshot, or a numbered list to visually and textually explain the process.
    • Example: docs/capabilities/data-platform/catalog.md

  • 3. Key Features / Technical Benefits

    • Purpose: A scannable, bulleted list that summarizes the most important technical advantages and features for the builder. This section focuses on the practical benefits a user gains from the tool.
    • Example: docs/capabilities/governance/projects.md

  • 4. Related Capabilities

    • Purpose: To provide dense cross-linking to other relevant pages, reinforcing the integrated nature of the platform and encouraging further exploration. Every component page should link to at least 3-4 other pages.

  • 5. The TARS Admonition: Proactive AI Assistance

    • Purpose: To showcase the power of our vertically integrated AI, we embed TARS tips directly within the workflow documentation using admonition blocks. This strategy mirrors how TARS functions in the product—as an omniscient, proactive assistant that offers high-impact suggestions in the context of the user's current task.
    • Implementation: These tips are always framed as value propositions, demonstrating how TARS accelerates a specific, relevant step in the builder's journey.
    !!! tip "AI-Assisted Transformation with TARS"
    At this step, you can ask [**TARS**](../ai-platform/tars.md) to accelerate your work by generating complex SQL for you. Instead of writing the query manually, you can provide a prompt like:
    > "Suggest a SQL query to join `@dataset_A` and `@dataset_B` on the `user_id` column, and filter for users in `Mexico`."
    TARS will generate the correct SQL directly in your editor.