Summary of #549: Great Docs

Overview of Talk Python to Me #549: Great Docs

In this episode, Michael Kennedy talks with Rich and Michael Chow from Posit about Great Docs, a new Python documentation tool designed to make doc sites look polished, work well for humans, and be easy for AI agents to consume. The conversation covers Great Docs’ design philosophy, its relationship to tools like Sphinx, MkDocs, Zensical, and Quarto, and why its opinionated, “great out of the box” approach may be especially useful for modern Python projects.

What Great Docs Is

Great Docs is a Python documentation site generator that aims to be:

• Fast to start
• Opinionated and polished by default
• Friendly to both humans and LLMs/agents
• Flexible enough for package docs, guides, and static content

Rich describes it as filling a gap similar to the “package-down” experience from the R ecosystem: point it at a Python package and quickly get a usable documentation site with minimal setup.

Core workflow

• great docs init creates a config file
• great docs build generates the site
• great docs preview serves it locally
• great docs build --watch supports fast iteration

The output is a static site directory that can be deployed anywhere static files are hosted.

Key Design Ideas and Features

Human-friendly documentation

Great Docs emphasizes presentation and structure:

• API reference pages generated from docstrings
• User guides and general content pages
• Styled elements like badges/tags
• Tabbed install instructions for different platforms
• A built-in search/filtering experience on reference pages
• Support for versioned docs and version selectors

AI-friendly documentation

A major theme of the episode is that documentation now has two audiences:

1. Humans reading the site
2. AI agents reading or parsing it

To support that, Great Docs includes:

• Markdown renditions of pages
• An LLMs.txt file
• A full markdown-formatted docs export
• Simple ways for agents to access content directly
• Page-level metadata and skill/discovery support

Michael Kennedy notes that this aligns with his own experience on Talk Python, where he added .md views and other machine-friendly entry points for SEO and AI workflows.

How Great Docs Uses Quarto

Great Docs is built on Quarto as the underlying publishing system.

What Quarto contributes

• Executable code blocks
• Rich document outputs
• Tabs, callouts, and structured content
• Support for freeze/caching workflows
• Cross-language publishing capabilities

Rich and Michael explain that Great Docs aims to hide much of Quarto’s complexity while still benefiting from its power. In other words, users can get a clean documentation workflow without needing to deeply understand Quarto internals.

How It Compares to Other Tools

The episode places Great Docs in the broader docs ecosystem:

Sphinx

• The traditional Python documentation powerhouse
• Used by major projects like Python itself and Pandas
• Built around reStructuredText
• Extremely established, but less modern-feeling for many users

MkDocs / Material for MkDocs

• Popular modern static site docs tooling
• Often used for product docs and project documentation
• More lightweight and approachable than Sphinx for many teams

Zensical

• A newer docs/static-site tool with compatibility goals around MkDocs
• Also moving toward broader knowledge-base and documentation use cases

Hugo and Ghost

• General-purpose static site generators
• Better suited for blogs or broader content sites
• Less focused on package API introspection and docstring-driven docs

Quarto / Quartodoc

• Quartodoc is a more minimal documentation generator on top of Quarto
• Great Docs builds on similar ideas but is more opinionated, stylized, and all-in-one

The main distinction: Great Docs wants to give you a beautiful, useful docs site immediately, rather than making you assemble every part yourself.

Notable Themes and Takeaways

1. Documentation is a workflow, not just a page

The hosts emphasize that docs are part of the development pipeline:

• Generate docs
• Preview them locally
• Freeze outputs if needed
• Publish to static hosting
• Keep docs aligned with code and releases

2. Good table and docs design are about communication

The conversation ties Great Docs back to Rich’s work on Great Tables, where the focus is on helping people communicate information clearly and elegantly, not just “display data.”

3. Rich’s design instincts drive the project

Michael repeatedly highlights Rich’s unusual sense of style and UX intuition. The project reflects many small decisions that make documentation more pleasant:

• Filterable reference pages
• Copy-to-markdown behavior
• Nice defaults for installation and versioning
• Careful visual structure

4. AI support is becoming essential

The episode strongly suggests that modern docs should be built for both:

• human readers
• AI systems that extract, summarize, and use documentation

Great Docs is explicitly designed with that future in mind.

Roadmap and Future Ideas

Rich shared several directions for Great Docs:

• More support for MCP server documentation
• Better documentation for new AI-era project types
• Expanded “skills” publishing and browsing
• More AI/agent-friendly discovery features
• Continued refinement of the docs experience and layout

There was also discussion of possibly adding even more publishing targets or better guidance for common deployment destinations.

Open Source and Sustainability

The episode also touches on the sustainability of the Posit open source ecosystem:

• Posit employs people working full-time on open source
• Projects tend to have long-lived maintainers
• Collaboration across tools and upstream dependencies matters
• This helps ensure projects don’t become abandoned

Michael highlights that sustaining open source also means contributing to shared tooling upstream, not just building competing products.

Final Thoughts

Great Docs is presented as a modern, polished, AI-aware documentation system for Python that aims to reduce friction without sacrificing quality. If you want:

• quick package docs
• elegant static sites
• executable examples
• versioned documentation
• markdown outputs for agents
• a strong out-of-the-box visual experience

…then Great Docs is worth watching closely.

The episode closes with an invitation for feedback and early users, since the project is still new and actively evolving.