Abundant with life: docs beyond the wall
Session Abstract
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?
Session Description
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](https://www.writethedocs.org/documentarians/) 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](https://www.sphinx-doc.org/en/master/) and [Asciidoc](https://asciidoc.org/) in passing, but I’ll particularly highlight [Markdoc](https://markdoc.dev/) 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.
