How Apache Superset Reinvented (and Re-engineered) Its World of Documentation

### Overview In this talk, a committer, PMC member on Apache Superset, and employee at Preset discusses the overhaul and re-engineering of Apache Superset's documentation ecosystem. Apache Superset is an open-source business intelligence, data visualization, and data analytics platform with over 74,000 GitHub stars. As the project grew, its documentation became fragmented across numerous wikis, README files, and blogs, creating a major maintenance bottleneck where documentation frequently fell out of sync with code changes.

While many turn to fully AI-generated documentation tools, the speaker cautions against letting AI write docs wholesale, noting that such tools often produce generic text, unhelpful architectural diagrams, and miss critical project nuances. Instead, Superset adopted a philosophy of using code and AI-generated transformation scripts to deterministically extract metadata and documentation directly from the codebase itself, centralizing everything on Docusaurus.

### Key Topics - **Documentation Fragmentation and Tooling**: Superset had roughly 50 scattered READMEs, wikis, and markdown files. Superset migrated to Docusaurus because of its multi-instance versioning and rich extensibility. - **Automating Docs from Codebase Metadata**: Using Python and JavaScript transformation scripts to convert codebase configurations, decorators, and specifications directly into markdown pages. - **Visual and UI Automation**: Leveraging testing tools like Playwright and React Storybook to automate screenshots and interactive component galleries. - **The Role of AI in Documentation**: Using AI to write the parsers, transformers, and PR summaries rather than having it draft narrative documentation from scratch.

### Technical Details Superset implemented several automated pipelines to build documentation directly from code: - **Country Maps**: A Jupyter notebook that generates GeoJSON map files also outputs JSON consumed by documentation to list available countries. - **Feature Flags**: Python decorators added to the configuration files store lifecycle metadata and descriptions. A transform script extracts these decorators to generate human-readable markdown tables automatically whenever configurations change. - **API Documentation**: Replaced basic Swagger files with an ecosystem of Docusaurus extensions providing multi-language code examples and response schemas. - **Database Engine Specs**: Database connection strings, supported features, and time grain expressions reside in `DB engine spec` Python files. Transform scripts extract this functional metadata to produce individual database documentation pages, an interactive filterable database overview page, and a database logo wall synchronized with the main repository README. - **Component Documentation**: Automated scripts convert React Storybook files into live documentation pages featuring prop knobs, component galleries, and an embedded live code editor. - **Playwright Screenshot Automation**: End-to-end Playwright test scripts take scoped UI screenshots and save them into the repo, updating visual assets across doc versions via an npm command. - **Future Automations**: Ongoing initiatives include generating docs for theme tokens, VS Code-like extension registries parsed from `package.json` files, MCP tools and skills documentation, automated PR-to-release-notes summarization, and harvesting recurring user questions answered by AI bots to identify documentation gaps.

### Takeaways The central thesis is to treat documentation as code by extracting it from codebase metadata using deterministic scripts. Rather than letting AI generate documentation that may be inaccurate or unhelpful, teams should use AI to write the transformation scripts that pull from the source of truth. This approach reduces manual maintenance PRs, ensures docs rebuild automatically on pull request merges, preserves historical versioning, and provides high-quality corpus data for both human users and AI coding assistants.