Code in Content: Using Dynamic, Interactive Elements in your Technical Writing¶
Description
As modern web technology has evolved, documentation has grown with it – leading to documentation that delivers an app-like experience to end users. For technical writers, there’s a growing emphasis on integrating code and logic directly into your content. New tools, like MDX and Markdoc, have emerged to bridge that gap, making it possible for writers to create dynamic, interactive content while writing in familiar Markdown syntax. But combining code and content can be challenging, add complexity, and create new and interesting ways to break things. So how should we think about and use these new tools to supplement our technical writing?
This talk will cover the “why” and “how” behind the code-in-content trend and examine the technologies powering it. We’ll introduce and compare Markdoc with MDX using real examples to explore the authoring experience they provide. We’ll take a pragmatic look at the practical benefits and tradeoffs of these tools, then consider how they fit into your writing by centering the end-user’s experience. You’ll leave this session with the knowledge and context you need to start using code in content, ready to transform your documentation into a powerful educational tool (without overdoing it).
- Conference: Write the Docs Portland
- Year: 2024
