Chris Ward (Docker): Dynamic Docs

This talk was presented at the API The Docs Amsterdam 2023 conference on 6-7 June. We are glad to present the video recording and the talk summary.

Visit the talk listing page for an overview of all presentations!

Chris Ward

Staff Technical Writer at Docker 

Chris' Presentation (video recording)

“Now we have all these fantastic advancements in web technologies from the past thirty years, why do we insist on still having such static walls of text?"

In the demo, you can hear about:

• The potential of dynamic documentation to enhance concepts like
  • content reuse,
  • getting content from other sources,
  • replacing screenshots,
  • using user data and interactive playgrounds in the documentation,
  • and using the documentation content in other places.
• Using tools like Astro and Docusaurus and technologies like MDX to create dynamic documentation.
• The paradigm shift brought on by React: everything is a component, including content.
• MDX and its ecosystem: Remark and Rehype can be used for manipulating the Markdown and the generated HTML respectively.
• The advantages & disadvantages of the developer-focused tools and technologies used in creating dynamic documentation.

Takeaways

• Every Markdown or MDX file can be treated as a component.
• In the content, include Markdown or MDX files as content components and pass variables to them (e.g., from user data) to provide dynamism and variability in the single-sourcing of the components.
• Use APIs to dynamically load data from sources (e.g., issue trackers, road maps).
• Instead of making screenshots, you can load live frontend components into the documentation.
• You can load dynamic user data into the components to show data that is relevant to the person reading the documentation.
• Creating interactive playgrounds in-line in the documentation makes sense as the toolchains overlap.
• Leverage plugins and tools from the Remark and Rehype ecosystem to convert written content to JavaScript or JSON formats.
• Take into account the advantages and disadvantages of using developer-focused tools and technologies.