Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Add comprehensive documentation structure for user success journeys #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
Copilot wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Add comprehensive documentation structure for user success journeys #25

Copilot wants to merge 2 commits into from

Conversation

Copy link
Contributor

Copilot AI commented Dec 29, 2025 •
edited
Loading

ChartSpec lacked structured documentation for key workflows: quick browser trials, dataset integration, schema understanding, and deployment. Users had to piece together information from scattered README sections.

Changes

Documentation Hub (docs/index.md)

  • UI comparison matrix (Classic vs Workbench)
  • Operating mode decision tree (LLM/Smart/Local)
  • User journey quick-start paths
  • Failure mode troubleshooting index

Schema Reference (docs/schema.md)

  • Complete ChartSpec field documentation with types and constraints
  • Examples for all 9 chart types (bar, line, scatter, pie, histogram, box, heatmap, table, facet)
  • Filter types (array, equality, operator) with validation rules
  • Common patterns: Top-N sorting, grouped aggregations, faceted charts

Architecture Guide (docs/architecture.md)

  • Pipeline stages: prompt parsing → data transformation → rendering
  • Renderer abstraction with BaseRenderer interface
  • Step-by-step: adding new renderers (with code examples)
  • Extension points: LLM providers, aggregation functions, filter types

Dataset Management (docs/datasets.md)

  • Storage strategies: localStorage limits vs IndexedDB for large data
  • Demo gallery mechanics (Socrata integration, caching, TTL)
  • Sampling strategies: random, stratified, top-N
  • Paging patterns for datasets >10MB

Testing Guide (docs/testing.md)

  • Playwright test infrastructure and __TEST_MODE__ flag usage
  • Local development loop with dev server
  • Test patterns: element waiting, dialog handling, error capture
  • Debugging techniques for flaky tests

Deployment Guide (docs/deployment.md)

  • GitHub Pages: root vs /docs deployment options
  • Link hygiene: relative URLs for subdirectory compatibility
  • Common failures: 404s, missing styles, CORS, out-of-sync files
  • Custom domain DNS setup

README Updates

  • Quick Start: 2-minute browser trial path
  • Enhanced security section: localStorage-only API keys, never commit
  • Mode comparison table with use cases
  • Links to new documentation structure

Example: ChartSpec with Filters and Aggregation

{
  "chartType": "bar",
  "x": "Region",
  "y": "Revenue",
  "filters": [
    { "type": "array", "column": "Region", "values": ["North", "South"] },
    { "type": "op", "column": "Revenue", "operator": ">", "value": 1000 }
  ],
  "groupBy": {
    "columns": ["Region"],
    "aggregations": { "Revenue": { "func": "sum" } }
  },
  "sort": { "column": "Revenue", "order": "desc" },
  "limit": 10
}

All documentation uses relative URLs for GitHub Pages compatibility and includes failure mode sections.

Original prompt

You are the repo documentation agent for a browser-based charting tool that generates a structured chart specification from natural language and renders it.

Goal: make users successful in these journeys:

  • “Try it in-browser in 2 minutes”
  • “Add my dataset and get a chart”
  • “Understand the ChartSpec schema and extend renderers”
  • “Run tests and ship to GitHub Pages”

Rules:

  • Use the existing UI modes and file structure; do not rename components in docs.
  • Every doc page should include a short “What you’ll learn” section.
  • Keep the ChartSpec JSON schema as the single source of truth; document it carefully.

Deliverables:

  1. README.md improvements

    • Clear 3-mode explanation (LLM mode / Smart mode / Local mode)
    • Security note: API keys stay in browser storage; never commit keys
    • Link to schema docs, renderer docs, dataset docs

  2. docs/index.md

    • UI map (classic vs workbench)
    • Link hub: schema, renderers, datasets, storage, testing, deployment

  3. docs/schema.md

    • Fully documented ChartSpec fields: filters, groupBy, sort, limit, chartType, encodings, facet
    • Include valid JSON examples for each chart type

  4. docs/architecture.md

    • Pipeline diagram: prompt → spec → transform → render
    • Renderer abstraction: how to add a new renderer safely

  5. docs/datasets.md

    • Dataset registration, limits, caching strategy, demo gallery mechanics
    • Guidance for large datasets (sampling, paging)

  6. docs/testing.md

    • How Playwright tests run; test mode flags; local dev loop

  7. docs/deployment.md

    • GitHub Pages publishing (root vs /docs) and link hygiene

Quality checks:

  • All examples use relative URLs where possible (Pages-safe).
  • Document “failure modes”: invalid spec, missing columns, storage quota, renderer load failure.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

@evcatalyst
Add comprehensive documentation structure
55a79e4 
- Improved README with clear 3-mode explanation and security notes
- Created docs/index.md as documentation hub with UI map
- Created docs/schema.md with complete ChartSpec field reference
- Created docs/architecture.md with pipeline diagram and renderer guide
- Created docs/datasets.md with dataset management and demo gallery
- Created docs/testing.md with Playwright testing guide
- Created docs/deployment.md with GitHub Pages deployment guide
- All documentation includes "What you'll learn" sections
- Documented failure modes for each area
- All examples use relative URLs for Pages compatibility

Co-authored-by: evcatalyst <[email protected]>
Copilot AI changed the title [WIP] Enhance documentation for browser-based charting tool Add comprehensive documentation structure for user success journeys Dec 29, 2025
Copilot AI requested a review from evcatalyst December 29, 2025 15:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@evcatalyst evcatalyst Awaiting requested review from evcatalyst

Assignees

@evcatalyst evcatalyst

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@evcatalyst