In this episode, I talk with Florian Lefebvre, a core maintainer of the open source Astro framework, about what it looks like to write and contribute to docs as a developer. We discuss his mindset shift from being reluctant about docs to seeing them as essential to shipping a feature, how he collaborates with a dedicated docs lead through "talking and doc-ing" calls, the importance of writing changesets from the user's perspective, and how reviewing community contributions doubles as a way to teach new contributors your project's docs conventions.

—

Florian and I discuss his path into the Astro core team, which started with answering questions on the project's Discord as a user and eventually led to being invited to join the core team. He shares how he was initially reluctant about writing docs, but his perspective shifted as he came to see docs as inseparable from shipping a feature. As Florian puts it, if you build something and nobody knows it exists or how to use it, your feature doesn't really exist.

A central thread of our conversation is Florian's collaboration with Sarah Rainsberger, the Astro docs lead. We dig into their "talking and doc-ing" calls, where Sarah reads back her understanding of a feature and the two iterate together until the docs are technically accurate. Florian highlights how having a dedicated docs lead removes a lot of pressure, especially as a non-native English speaker. He can focus on getting the technical content right and trust Sarah to handle phrasing. We also discuss the value of asking "Is this what you meant?" as a confidence check, rather than making edits based on assumed understanding.

Beyond the collaboration with Sarah, we also cover the practical side of contributing docs as a developer, including reviewing community PRs, writing user-focused changesets, and handling docs for experimental features. Florian explains his approach to coaching new contributors through review comments rather than pointing them to guidelines, why he writes changesets focused on what the user cares about rather than what the developer did to fix something, and how Astro keeps experimental feature docs as a single page until the feature stabilizes. Florian closes with a small but powerful philosophy from the Astro Docs team: every contribution just has to be "not worse than what we had before."

Fullstack developer. Freelancer. Astro core maintainer & TSC member. Open-Source lover. French. Two-time winner of the Astro Community Award.

Join the discussion by replying on Bluesky

—

We love hearing your ideas for episode topics, guests, or general feedback: