Skip to main content

JP Hwang (Weaviate): Tests: The next step for docs-as-code

API The Docs 2023 Developer Success: Looking Beyond Developer Experience Recap

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!


JP Hwang

Technical Curriculum Coordinator at Weaviate


Hwang's presentation (Video recording)

“Without testing, there is no way to ensure that our documentation is up to date with the codebase. At Weaviate we love tests. More tests are always better tests.”


In the demo you can hear about:

  • The benefits of adding automated tests on documentation, which include increased confidence in code samples, improved modularity, and a simplified workflow.
  • Why it’s easy to add code snippets but difficult to maintain them: it can be challenging to recall details later, and errors might not be immediately visible.
  • Maintaining code examples at Weaviate involves using 6-7 languages, multiple database configurations and datasets.
  • Weaviate’s journey to testable documentation through multiple iterations.
  • How treating code examples as code transformed the way the team approached code snippets and their function in the documentation.
  • Adopting a “code-as-docs” instead of a “docs-as-code” approach to signify the shift in perspective.


  • Automated tests on the documentation drive developer success.
  • Testing increased confidence in code examples, and simplified the workflow in spite of the added steps.
  • Adding code snippets is the easy part, maintaining them can be a challenge.
  • Without testing, there’s no way of making sure the documentation is up to date.

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.


Sign up


Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.