FOSS Backstage 2025

Abundant with life: docs beyond the wall
2025-03-10 , bUm Box

Our docs are living systems, but too often we've imagined them merely as flattened walls of text, and not much more. So, let's take a more holistic perspective of how folks interact with software documentation. Many of them wish to engage more actively, not just as passive consumers. How do we enable them?


Let's bring some enthusiasm and energy back to the practice of documentation. Let's think intentionally and mindfully about it. Let's think beyond static content.

This presentation primarily addresses folks who already understand why it's important to maintain and invest resources in documentation. Perhaps you've already deployed a static site generator for your project's docs, or you've made some open-source documentation contributions. But if you are new to documentation, no worries. I'll briefly discuss some known best practices and helpful tools for writing and maintaining so-called "good" documentation.

No matter what, I hope this presentation awakens the documentarian in you.

Here, I'll refer to user experience (UX) in terms of developer experience and authoring experience. Together we'll examine some tools and frameworks that support the overall documentation experience: in terms of caring for them as a maintainer or contributor, and in terms of engaging with them as a user. I'll introduce Sphinx and Asciidoc in passing, but I'll particularly highlight Markdoc as a framework that enriches the developer experience and authoring experience.

Here, we'll see more clearly a wall that has inexplicably and unnecessarily separated these experiences from each other for years, resulting in an industry-wide misunderstanding of documentation that persists today. I hope this presentation leaves you feeling invigorated with a renewed sense and new ideas for what's possible for your documentation, regardless of which tools you choose. In the meantime, let's take a hammer to that wall.

Advocate for technical documentation and active participant in the Write the Docs community since 2017. Transplanted from Los Angeles to Berlin in 2021. These days, you can find her at a WTD Berlin meetup. Come say hi!