Skip to main content

Lana Novikova (Jetbrains): Using Domain-Specific Languages (DSLs) to Document API — the Kotlin DSL story

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!


Lana Novikova

Technical writer at Jetbrains



"What we have tried to make is to make an Internal DSL that can act as external…"


In the demo, you can hear about:

  • How the experiment started with an internal hackathon. 
  • The definition of DSL: a programming language with a higher level of abstraction, optimized for a specific domain. We can distinguish two types of DSLs:
  • External (like SQL): it’s a separate language and has custom features,
  • Internal (such as Kotlin DSL): uses host language features.
  • The goal: to make an internal DSL that can act as external.
  • An example of how it works: 
    • Simplistic documentation DSL: using semantic elements, like chapters, lists, etc.
    • It’s possible to inject other languages into Kotlin (e.g., XML).
  • Separation of content and presentation compared to Kotlin DSL’s capabilities.
  • Docs-as-code → Docs-are-code.
  • Use practices brought to technical writing by developers.
  • Demonstration of how Kotlin DSL works.
  • Why you should choose Kotlin DSL.


  • Anything is possible, but you need to know how: ask for help from programmers and fellow technical writers.
  • Kotlin DSL provides a great deal of flexibility, but be aware that this flexibility leads to more fragmentation.
  • Kotlin DSL helps to start coding more smoothly.

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.