Zainab Ali is a functional programmer, educator, open source contributor and organizer of the London Scala User Group. For the past five years, she’s helped developers master the art of functional programming in Scala. She’s particularly interested in the challenges of writing effective technical documentation and training materials.
When programming, documentation typically takes a back seat to development.
There are good reasons for this: documentation tends to be hard to maintain, as well as write, and the tools for working with it can be slow and painful to use.
But writing documentation is very similar to writing code: it's just that we don't have a great language for it yet.
This talk poses the idea that docs are programs. If they are programs, what does their ideal programming language look like?
To address this question, we treat documentation as an artifact produced by compiling a codebase of input sources.
We see that, like a typical programming pipeline, a documentation pipeline has phases of expansion, symbol linking and compilation errors, but that it also has its own unique concerns around maintenance of structure and flow.
In the search for our ideal language, we'll explore documentation strategies in a variety of ecosystems. We'll encounter Pollen in Racket, Elixir Livebooks, mdoc in Scala, and see how these influence our experience of writing docs.
At the end, we'll have a vision of what doc developer experience could be. You might not enjoy writing docs, but you'll learn how to improve your workflow, and even be inspired to develop your own documentation tooling.
Searching for speaker images...