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."

About Florian Lefebvre:

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

In this episode:

• [00:01:38]: Florian's origin story: from coding his high school orchestra's website to joining the Astro core team
• [00:03:22]: Astro's governance: maintainers, core maintainers, and how community involvement leads to those roles
• [00:05:19]: Astro features Florian has contributed: Astro Env and the Fonts API
• [00:11:01]: From reluctant docs contributor to seeing docs as essential to shipping a feature
• [00:13:50]: How Astro's docs work: a dedicated docs lead plus community contributions
• [00:14:58]: Community contributions and the "banner everywhere" problem
• [00:17:10]: Astro Docs Docs and coaching new contributors through review comments
• [00:22:44]: Writing changesets that focus on what the user cares about, not what the developer did
• [00:32:57]: Docs for experimental features: the single-page approach
• [00:40:44]: Using existing pages as templates for new docs
• [00:42:45]: Writing docs as a non-native English speaker
• [00:46:55]: The "talking and doc-ing" call process: drafts, iteration, and confidence checks
• [00:52:51]: Resource recommendations: Astro Docs Docs, Diátaxis, and Sarah's 50 docs tips
• [00:54:21]: Florian's best advice: every contribution should be "not worse than what we had before"

Resources discussed in this episode:

• Astro Docs
• Astro Docs Docs - Astro's docs about contributing to and writing for their docs
• Astro Env - The environment variables feature Florian contributed to Astro
• Astro Fonts API - The fonts feature Florian worked on
• Starlight - A docs framework built on top of Astro
• The Diátaxis framework
• 50 docs tips in 50 days - Sarah Rainsberger's blog series

Also recommended by Florian:

• Supporting the future of Astro

Join the discussion by replying on Bluesky

—

Contact The Not-Boring Tech Writer team:

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

• Email: [email protected]
• thenotboringtechwriter.com
• LinkedIn
• Bluesky
• Guest suggestions form

Contact Kate Mueller:

• knowledgewithsass.com
• LinkedIn
• Bluesky

Contact Florian Lefebvre:

• florian-lefebvre.dev
• LinkedIn
• Bluesky

Contact KnowledgeOwl:

• knowledgeowl.com
• LinkedIn