Tool the Docs
How Apache Superset reinvented (and re-engineered) its world documentation
<p>The addition of a new Extensions SDK in Superset led to a new initiative: a Developer Portal.</p>
<p>That, in turn, gave us the chance to re-imagine how we WANT our docs to work:
• Bringing in scattered readmes/wikis/etc. under one roof
• Creating independently versioned areas for different release cycles and intents
• Automating screenshots and content to "keep up" with the codebase
• Bringing API docs, React Story book, and more into a centralized interactive portal
• Leveraging AI to build and maintain docs... for people AND for humans
• Syndicating content from third party sources to be the end-all-be-all of Superset documentation
• Leveraging AI (for free!) to provide chat-based support AND learn where our docs are falling short from the result</p>
<p>We've learned a lot of hard lessons over the years, and we're happy to share the process, ideas, and tools we've used to take things to the next level.</p>
Additional information
| Live Stream | https://live.fosdem.org/watch/ud2208 |
|---|---|
| Type | devroom |
| Language | English |
More sessions
| 1/31/26 |
<p>Welcome and update on the logistics of the dev room</p>
|
| 1/31/26 |
<p><a href="https://lfenergy.org/projects/seapath/">LF Energy SEAPATH</a> is an open source, high-availability real-time platform designed for hosting virtualized protection and control applications within electrical substations. As a complex project bridging electrical and computer engineering, it integrates multiple open source tools and expertise from diverse domains. Following the recent release of version 1.0, the project undertook a refactoring of <a ...
|
| 1/31/26 |
<p>Documentation is the backbone of successful projects, yet many tools fall short in balancing ease of use, collaboration, and flexibility. <strong><a href="LaSuite Docs">https://github.com/suitenumerique/docs</a></strong> is an open source, block-based editor designed to solve these challenges. Built by the French and German govs, it offers a snappy editing experience, real-time collaboration, fine-grained access control, and powerful features like sub-docs and a headless CMS API. This talk ...
|
| 1/31/26 |
<p>Sometimes you need to mark up what Markdown doesn’t. It’s tempting to pick up a heavyweight Markdown variant, such as MDX, or to build your own just-this-once extension. But extensions to Markdown are often eye-wateringly ugly, fragile, and prone to lock-in. What’s to be done, switch formats? No, you’re too busy for that.</p> <p>In this talk, I’ll teach you about the little-used extension points that already exist in mainstream Markdown flavors, such as CommonMark, and how to take ...
|
| 1/31/26 |
<p><a href="https://www.docling.ai/">Docling</a> is an open source toolkit that simplifies document processing by converting various formats like PDFs and Word documents into structured, searchable data. It can handle complex layouts, tables, code, and formulas to preserve the meaning of the data and maintain the formats and relationships of the information. Find out how you might include <a href="https://github.com/docling-project">Docling</a> in your documentation workflow to emcompass diverse ...
|
| 1/31/26 |
<p>You've perfected your Docs-as-Code pipeline. Your HTML documentation is beautiful, version-controlled, and deploys instantly. Then someone asks for a printing version. Printing? What is it? Ah, a primitive pre-HTML way of publishing, no problem... until you try it.</p> <p>This talk addresses the fundamental mismatch between the web's fluid layout and the paged, fixed-layout world of print. After creating Asciidoctor to Open Document converter ...
|
| 1/31/26 |
<p>Documentation often lags behind code changes, leading to inconsistencies and outdated information. This session explores how to automate the generation of comprehensive and up-to-date documentation using a custom Yaml-based domain-specific language alongside Asciidoctor and Antora. By defining product behavior in a DSL, we not only produce the framework for software code but also generate the bulk of the documentation, making the DSL the single source of truth for the project. We'll discuss ...
|
