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 Bret Victor 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 o