4 ms·

> the best way to do that would be to make tools that make beautiful documentation easy. Really? I find it hard to believe that the problem is caused by a lack

> the best way to do that would be to make tools that make beautiful documentation easy. Really? I find it hard to believe that the problem is caused by a lack of tools. Clojure already has five or six tools for spitting out a programmatically-generated HTML overview of the shape a given project. Instead I think it's clear the reason this doesn't happen is that good documentation is really difficult to write and people don't want to put the necessary effort into it. Putting aside the obvious problem that good English prose is really difficult to write, you have to overcome the fact that the people qualified to write the documentation don't much benefit from it. On top of that, it's very difficult for an experienced user to put himself in the mindset of a beginner. In fact, I'd go so far as to say that the existence of all this existing documentation tooling only goes to reinforce the harmful notion you can just run something like marginalia over your codebase and publish the HTML output somewhere and consider your project documented. Sure, API overviews are valuable as a reference, but they're mostly just a distraction to someone starting out who just wants to figure out whether the project is a good fit for their needs. Long-form prose documentation is crucial at that stage, and it's awfully hard to come by. http://jacobian.org/writing/great-documentation/what-to-write/ http://jacobian.org/writing/great-documentation/what-to-writ... Anyway the tooling is trivial--getting an overview of the API and docstrings has been done over and over, and rendering a pile of prose in markdown files is hardly rocket science. The real problem is cultural.

ibdknox 14y ago
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.
- technomancy 14y ago
  Maybe. I'll withhold my judgment till I actually see such a tool, but I suspect tooling and design function more as distractions when it comes to documentation; in my eyes the only thing that matters is content.

ibdknox 14y ago

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.

technomancy 14y ago
Maybe. I'll withhold my judgment till I actually see such a tool, but I suspect tooling and design function more as distractions when it comes to documentation; in my eyes the only thing that matters is content.