We don't actually disagree - I said just before that that we need to push it into the culture :) The way to do that is to make beautiful docs the norm, which is

We don't actually disagree - I said just before that that we need to push it into the culture :) The way to do that is to make beautiful docs the norm, which is what I tried to add to Noir and Korma. And you're right, it is really hard, but we need to at least convince people to try. While not solved purely at a tooling level, I think tooling can go a long way here by creating interesting and obvious ways to document things in a more meaningful manner than simple API docs. If the cannonical tools for the language are all encouraging you to write long form docs, I have a hard time believing that everyone will simply ignore that. In the end, however, it comes down to us; the people using the language and writing the libraries now to do exactly this. It's why I spent so long writing stuff for Noir and it's something we as a community that already exists need to do better.