After many years of writing and thinking about developer documentation, I'm convinced that the discipline is still in its infancy. The goal of this document is to summarize my current opinions on the topic of documenting software.
When you ask a software developer what their favorite documentation is, you'll get a wide range of opinions with consensus centering roughly around the Stripe and Twilio documentation, as well as the documentation for open source software like Django, Perl, Flask, etc.
In academia, the uncontested master craftsman of developer documentation is Donald Knuth, who pioneered "Literate Programming"
At the frontier of developer documentation, we find projects like Eve and other projects inspired by Bret Victor's seminal "Inventing on Principle" video.
However, as folks at Dynamicland will often point out, the medium (in the McLuhan sense of the word) of software hasn't changed much since the days when code was written on teletypes: We still write software on fancy typewriters. The tragedy of the best software documentation today is that it's all built within the boundaries and assumptions of the medium of paper.
Truly great developer documentation will take full advantage of the interactivity that the computational medium provides.
So far, the pinnacle of developer documentation seems to be the Genera OS from Symbolics, where the entire Operating System (down to the kernel!) was available for live inspection and modification by the end user, all documented using Document Examiner. In more general terms, software development needs to grow out of the limitations of a teletype based UX and take more advantage of the benefits of a fully interactive and immersive experiences that every modern computer is now capable of.
What does that mean in practical, and tactical, terms? In the long term, it's going to mean discovering a "humane dynamic medium" (as the researchers at Dynamicland are trying to do) and in the short term, this means embracing pop-culture developments like WebAssembly to blur the lines between where the "code" ends and where the "documentation" begins. The documentation for Vue.js is a good example of this.
However, because pop-culture shifts so quickly, we need a vision to guide us through the ever-changing computing fashions and trends. The "pragmatic" part is important, important not only because pragmatism is what pays the bills, but also because the mental models that people use change very slowly and we need to be pragmatic about what people will be able to deal with, conceptually.
My attempt at a pragmatic, medium-term vision for better developer documentation looks something like this: Documentation should be full of code, but that code should be fully interactive and able to be executed within the context of the documentation itself. Not only that, the code should always be able to be copied and run in whatever other development environment is currently popular for that particular programming language.