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.