Refactor documentation: consolidate product narrative and update messaging - #22
Merged
Merged
Conversation
New docs/getting-started/about.md explains why DBPort exists, who it's for (bridging data engineers and data scientists), column contracts as simplified SDMX, and when it's not the right fit. Registered in zensical.toml nav and getting-started index grid. README opening broadened to mention interdependent dataset families. docs/dbport.md removed — its content is now superseded by about.md. https://claude.ai/code/session_01Tg6Sn17JrnmR1S6WGc2WUp
Replace the bare link hub with a real page: opens with the problem (silent drift, corrupted publishes, lost provenance), shows a complete CLI/Python example, highlights key capabilities with icons, then links to the sub-pages. https://claude.ai/code/session_01Tg6Sn17JrnmR1S6WGc2WUp
Opens with the real pain (silent drift, corrupted publishes, lost provenance), shows full CLI/Python example, presents six key capabilities as feature cards, includes tool-fit comparison table, and ends with navigation grid. Mirrors the README tone while using Material for MkDocs features (tabs, grid cards, icons, buttons). https://claude.ai/code/session_01Tg6Sn17JrnmR1S6WGc2WUp
Lead with dependency tracking, input provenance, and recompute-on-change instead of schema drift and safe publication. Position DBPort as an orchestration/governance layer on top of the warehouse rather than just a lifecycle wrapper around individual model runs. https://claude.ai/code/session_01Tg6Sn17JrnmR1S6WGc2WUp
Walk readers through the concrete steps: bring your warehouse, set credentials, init a model, work in DuckDB, publish, then build the next model on top. Less repetition of the pitch, more focus on getting people productive. https://claude.ai/code/session_01Tg6Sn17JrnmR1S6WGc2WUp
Replace docs-focused roadmap with user-facing feature roadmap: extension system first, then input/model/orchestrator extensions, then warehouse backends, compute engines, and SDMX registry. Ordered by impact and implementation likelihood. https://claude.ai/code/session_01Tg6Sn17JrnmR1S6WGc2WUp
Add current release summary, roadmap preview, and navigation cards for roadmap, changelog, and release versioning policy. https://claude.ai/code/session_01Tg6Sn17JrnmR1S6WGc2WUp
Lower barrier to entry for teams without an Iceberg catalog, at the cost of reimplementing versioning in the domain layer. https://claude.ai/code/session_01Tg6Sn17JrnmR1S6WGc2WUp
- Add "Build locally. Publish safely." tagline to homepage - Add semantic colors (success/warning/error/info) to brand.css - Set Material palette to "custom" to avoid flash of wrong theme colors - Remove docs/brand.md (fully incorporated into site) https://claude.ai/code/session_01Tg6Sn17JrnmR1S6WGc2WUp
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR consolidates and refactors the documentation structure to present a clearer, more focused product narrative. Two lengthy product positioning documents (
dbport.mdandbrand.md) have been removed and their core concepts integrated into the main documentation flow. The homepage and getting started sections have been substantially rewritten to emphasize governance, orchestration, and dataset lifecycle management.Key Changes
Removed product narrative documents: Deleted
docs/dbport.md(391 lines of product story and positioning) anddocs/brand.md(156 lines of brand guidelines). This content was comprehensive but redundant with the actual product documentation.Rewrote homepage (
docs/index.md): Shifted from a brief tagline to a more substantive value proposition. Added "See it in action" section with CLI and Python examples, expanded "Why using DBPort" with six concrete benefits (dependency tracking, input provenance, recomputation, schema drift detection, versioned publishes, committable state), and clarified positioning relative to DuckDB, dbt, and orchestrators.Restructured getting started flow:
docs/getting-started/about.mdto answer "What is DBPort?" and "Who is it for?" upfrontdocs/getting-started/index.mdwith a clearer 6-step walkthrough (install → credentials → init → configure → run → build on it)Updated roadmap (
docs/versions/roadmap.md): Replaced vague documentation UX items with concrete product roadmap items (extension system, input extensions, model builder integrations, orchestrator integrations, S3+Parquet backend, additional warehouse backends, additional compute engines). Added impact/effort/timeline metadata for prioritization.Expanded versions index (
docs/versions/index.md): Added context about the project's development stage and structured the section with a card-based navigation to roadmap, changelog, and release versioning policy.Updated README.md: Changed tagline from "Versioned dataset recomputation on DuckDB, published to Iceberg" to "Governance and orchestration for recomputable warehouse datasets" and expanded the problem statement to emphasize model dependencies and orchestration.
Updated navigation and styling: Added
getting-started/about.mdto the nav structure inzensical.toml, refined CSS color tokens inbrand.css, and updated internal references inCLAUDE.md.Notable Implementation Details
The new "About" page (
getting-started/about.md) serves as a bridge between the homepage value proposition and the technical quickstart, answering conceptual questions before diving into setup.The roadmap now uses a structured format with impact/effort/timeline metadata, making prioritization and planning more transparent.
Product positioning language has been unified around "governance," "orchestration," and "dataset lifecycle" rather than the previous "production layer" framing, which better reflects the actual use case of managing dependencies between recomputable models.
The homepage now leads with concrete examples (CLI and Python) before explaining benefits, making the product immediately tangible to new users.
https://claude.ai/code/session_01Tg6Sn17JrnmR1S6WGc2WUp