Lana Novikova
Jetbrains
Using Domain-Specific Languages (DSLs) to Document API — the Kotlin DSL story
About the Talk
API docs can be challenging when it comes to maintaining consistency and expandability. The use of Domain-Specific Languages (DSLs) has emerged as a solution, with Kotlin DSLs being a promising option. In my talk, I will explore the benefits and pitfalls of using it to streamline documentation.
Documenting API can be a tedious and time-consuming task, especially when it comes to maintaining consistency and accuracy. Not to mention expandability and complex API architecture support. In this talk, we will explore how using Domain-Specific Languages (DSLs) specifically Kotlin DSL can help streamline the API documentation process, making it easier to create and maintain documentation while ensuring its accuracy and consistency. Kotlin DSL turned out to be a type-safe and concise language for documenting APIs that is easy to understand for both technical and non-technical audiences. Surely, there are already a bunch of DSLs to describe APIs (API Blueprint, RAML, and Swagger), but you can not work with them as with code and extend using libraries. During the internal hackathon, we approached API documentation using our own dialect of the Kotlin DSL and this turned out pretty convenient. We were able to combine declarative and imperative approaches to automate many things, as opposed to tools or markup languages whose feature set is limited. Since documentation is a kind of code now, we are able to tightly integrate it with test cases, BDD frameworks, UI and API testing tools, and so on. You can extend the language to support anything. If you ever wished there was a way to document your API that felt more like writing code, but easier, this talk is for you. I will explain how using Kotlin DSL can contribute to developer success by making it easier for developers not only to contribute to the documentation but improve and extend it. Let’s dive into the world of Turing-complete documentation together!
About the Speaker
Lana is a technical writer, an API writer, and a docops. For the recent 7+ years, she specialised in documentation for developers, API documentation, internal knowledge bases, and dev portals launches. She is an active member of the tech writing community (Write the Docs), and she often speaks at meetups and conferences. She loves a good meme, cider, and Formula 1 races.
