Dataface Tasks

Document faces/ directory convention and dbt project setup

IDDFT_CORE-DOCUMENT_FACES_DIRECTORY_CONVENTION_AND_DBT_PROJECT_SETUP
Statuscompleted
Priorityp1
Milestonem1-ft-analytics-analyst-pilot
Ownersr-engineer-architect
Completed bydave
Completed2026-03-16

Problem

The documentation inconsistently used dashboards/ as the directory for dashboard YAML files, but the actual convention across the CLI, all examples, and the playground is faces/. This caused confusion for users following the docs. Additionally, there was no clear guide for adding Dataface to an existing dbt project.

Context

  • The CLI defaults to faces/ (dft validate faces/, dft serve faces/)
  • All 51+ example files across examples/playground/faces/, examples/tutorial_dbt/faces/, examples/pied_piper_dbt/faces/, examples/dundersign_dbt/faces/ use faces/
  • The Cloud app uses dashboards/ internally (Cloud-specific mapping for its Django models), but external users interact with faces/
  • Docs that referenced dashboards/: getting-started.md, installation.md, cli-reference.md, best-practices.md, imports.md, queries.md, yaml-style-guide.md, charts/index.md

Plan

  1. Replace all dashboards/ references in docs with faces/
  2. Add "Adding Dataface to an Existing dbt Project" section to installation.md
  3. Document faces/ conventions: partials in faces/partials/_*.yml, subdirectories map to URL paths

Implementation Progress

Completed. All changes made in a single pass:

Files modified (dashboards/ → faces/): - docs/docs/guides/getting-started.md — project structure, file paths, CLI commands - docs/docs/guides/installation.md — directory creation, test file, verification steps - docs/docs/guides/cli-reference.md — 47 occurrences across all command examples - docs/docs/guides/best-practices.md — project organization, CLI examples - docs/docs/guides/yaml-style-guide.md — validation examples - docs/docs/boards/imports.md — directory structure diagrams - docs/docs/queries.md — validation/compile examples - docs/docs/charts/index.md — serve/validate examples

New content added: - docs/docs/guides/installation.md — "Adding Dataface to an Existing dbt Project" section with: - 4-step quickstart (install, mkdir faces, create hello.yml, serve) - Complete project structure diagram showing faces/, partials/, assets/ - Key conventions documentation (faces/ canonical, partials with _ prefix, subdirectories) - Explanation that Dataface auto-discovers dbt_project.yml

Review Feedback

  • [x] Review cleared