> Markdown version of [/videos/2054-why-is-software-documentation-still-static-and-why-modern-browsers-deserve-better](https://www.wearedevelopers.com/videos/2054-why-is-software-documentation-still-static-and-why-modern-browsers-deserve-better). Every page supports `.md` or `Accept: text/markdown`. Links point to the HTML versions so they work for humans too. Agent guide: [/agents.md](https://www.wearedevelopers.com/agents.md).

---

# Why Is Software Documentation Still Static – And Why Modern Browsers Deserve Better

Why force developers to leave your documentation to test code? Reimagining Markdown as an interactive environment lets users execute, edit, and iterate natively within their browser.

- **Speakers:** [André Dietrich](https://www.wearedevelopers.com/@andre-dietrich), [Jihad Hyadi](https://www.wearedevelopers.com/@jihad-hyadi)
- **Event:** World Congress 2026 Europe - Virtual Stage
- **Published:** July 2, 2026
- **Duration:** 29:19
- **URL:** https://www.wearedevelopers.com/videos/2054-why-is-software-documentation-still-static-and-why-modern-browsers-deserve-better

## Summary

Traditional software documentation relies on static publishing pipelines that convert Markdown to HTML, forcing developers to leave the documentation to test code, visualize data, or debug edge cases. However, modern browsers can support highly interactive, native execution. By reimagining Markdown not as a static format but as a dynamic environment, documentation becomes an active workspace where users can execute, edit, and iterate on code directly within the text.

Using tools like LiaScript, authors can embed JavaScript runtimes, HTML elements, and Web Components directly into Markdown files. This enables complex live tutorials—such as training a TensorFlow.js neural network or rendering Chart.js visualizations—without requiring local environment setups or complex static site generators. Boilerplate code can be abstracted away using custom Markdown macros, allowing writers to import reusable scripts, CSS, and interactive elements from external repositories just like standard software libraries.

Beyond simple code execution, interactive Markdown supports reactive data flows between individual code blocks and integrates native browser capabilities like text-to-speech for accessible learning. This decentralized, serverless approach eliminates the need for complex hosting infrastructure, empowering open-source maintainers and educators to easily build and share immersive open educational resources (OER). Ultimately, treating documentation as an explorable, interactive graph rather than a linear book drastically reduces the friction of developer onboarding and API adoption.

**Keywords:** interactive markdown documentation, static site generator alternatives, in-browser code execution, liascript authoring system, open educational resources, serverless documentation hosting, tensorflow.js live examples, interactive api tutorials, markdown macro substitution, reactive code blocks, web components in markdown, decentralized content authoring, browser-based developer onboarding, dynamic data visualization docs, text-to-speech educational content

## Chapters

1. **Setting up a live Markdown preview environment** (00:01) — Preparing a live demonstration of interactive Markdown documentation using GitHub and LiaScript.
1. **Why AI prefers HTML but developers need Markdown** (01:25) — The trade-offs between the rich interactivity of HTML generated by AI and the human readability of Markdown.
1. **Breaking the static documentation publishing loop** (02:33) — How traditional static site generation forces developers into a disjointed process of reading, copying, and local debugging.
1. **Analyzing boilerplate in TensorFlow JavaScript examples** (03:57) — Exploring how the scattered structure and heavy HTML boilerplate of TensorFlow JS documentation hinders learning.
1. **Shifting to a mental model of interactive Markdown** (05:55) — Empowering Markdown with native browser capabilities to eliminate static publishing steps and enable in-place execution.
1. **Executing JavaScript directly within a Markdown document** (07:39) — Embedding and running basic TensorFlow JavaScript code blocks inside a live Markdown editor.
1. **Managing console outputs and asynchronous function execution** (10:29) — Adapting the execution environment to capture console logs and handle asynchronous training loops without blocking.
1. **Rendering visual data with web components and Chart.js** (12:21) — Integrating external visualization libraries into Markdown to display training data dynamically without leaving the document.
1. **Reducing repetitive code with Markdown macros** (15:28) — Defining text substitution macros to hide boilerplate and create importable, interactive documentation libraries.
1. **Making dynamic elements first-class Markdown citizens** (17:27) — Embedding standalone script tags and browser internationalization features to build dynamic and localized tutorials.
1. **Binding data across responsive Markdown script inputs** (20:16) — Utilizing interactive sliders and asynchronous data fetching to automatically recalculate and update outputs across a document.
1. **Enhancing tutorials with animations and text-to-speech** (23:31) — Adding step-by-step code reveals and browser-based audio narration to support accessible, presentation-style learning.
1. **Publishing decentralized interactive open educational resources** (26:52) — Leveraging LiaScript and Git repositories to host free, extensible, and interactive courses without managing dedicated servers.

## Related Moments

- [Creating interactive educational content with LiaScript](https://www.wearedevelopers.com/videos/941-transforming-education-a-journey-from-interactive-markdown-to-remote-labs) (from "Transforming Education: A Journey from interactive Markdown to Remote-Labs")
- [Audience Q&A on AI documentation formatting and tools](https://www.wearedevelopers.com/videos/100199-making-documentation-ai-ready-preparing-your-docs-for-the-llm-era) (from "Making Documentation AI-Ready: Preparing Your Docs for the LLM Era")
- [Powering interactive JavaScript learning environments in the browser](https://www.wearedevelopers.com/videos/2135-wearedevelopers-live-streaming-html) (from "WeAreDevelopers LIVE - Streaming HTML")
- [Scripting interactive technical presentations inside the editor environment](https://www.wearedevelopers.com/videos/1766-devs-vs-marketers-cobol-and-copilot-make-live-coding-easy-and-more-the-best-of-live-2025-part-3) (from "Devs vs. Marketers, COBOL and Copilot, Make Live Coding Easy and more - The Best of LIVE 2025 - Part 3")
- [Presentation design and open source markdown tools](https://www.wearedevelopers.com/videos/532-policy-as-versioned-code-you-re-doing-it-wrong) (from "Policy as [versioned] code - you're doing it wrong")
- [Generating static web content with Markdown and Liquid templates](https://www.wearedevelopers.com/videos/1814-wearedevelopers-live-markdown-liquid-and-checkouts) (from "WeAreDevelopers LIVE - Markdown, Liquid and Checkouts")

## Related Articles

- [Dev Digest 130 - The Diablo is in the details](https://www.wearedevelopers.com/magazine/470-dev-digest-130-the-diablo-is-in-the-details)
- [Dev Digest 131 - AI'm not sure about OSS](https://www.wearedevelopers.com/magazine/472-dev-digest-131-ai-m-not-sure-about-oss)
- [Dev Digest 124 - None like it hot](https://www.wearedevelopers.com/magazine/460-dev-digest-124-none-like-it-hot)
- [Dev Digest 129 - Now that's what I call private data!](https://www.wearedevelopers.com/magazine/468-dev-digest-129-now-that-s-what-i-call-private-data)

## Related Jobs

- [Staff Developer Advocate, GitHub Security Lab](https://www.wearedevelopers.com/jobs/ext/1921051-staff-developer-advocate-github-security-lab) at **GitHub**
- [Senior Software Engineer, React (Websites & Martech)](https://www.wearedevelopers.com/jobs/ext/1605272-senior-software-engineer-react-websites-martech) at **Bitpanda**
- [Staff Software Engineer, Copilot Experiences](https://www.wearedevelopers.com/jobs/ext/164361-staff-software-engineer-copilot-experiences) at **GitHub**
- [Senior Software Engineer](https://www.wearedevelopers.com/jobs/ext/15942-senior-software-engineer) at **GitHub**
- [AI Software Engineer (Germany)](https://www.wearedevelopers.com/jobs/48317-ai-software-engineer-germany) at **Sunhat**
- [Principal Software Engineer, Enterprise AI Platform](https://www.wearedevelopers.com/jobs/ext/1467292-principal-software-engineer-enterprise-ai-platform) at **GitHub**