I'd like to highlight an issue with the docstrings as they stand. It has been stated by Rich himself on Jira that he doesn't like or want usage examples in docstrings. However, it would seem that many other people would love to see exactly that; myself included.

He made this clear a few years ago - I don't know if he has changed his mind since?

This would probably help beginners more than anybody else.

docstrings are intended to be a concise statement of what the function does and we would like to stick with that.

Examples are also great. We would love to have documentation pages (or even doc functions in the repl) that combine multiple sources of information to help you out (docstrings, examples, see alsos, etc). That stuff does not have to be "in the docstring" for it to be available to you as a user.

For example, clojuredocs.org does exactly this, combining multiple sources of information into one combined page (ex: http://clojuredocs.org/clojure.core/zipmap). There used to be an api for clojuredocs.org and a repl lib you could use that would give you an additional function to get those examples at the repl too (I think that fell out of maintenance).

The summary is, we can both have docstrings that don't include examples AND provide examples by merging docstrings with other things for the user.

Thanks for explaining the rationale, as well as future hopes and plans for documentation.

Yes, I have done both.

Thank you for your tireless work on improving Clojure and the surrounding ecosystem.

Thanks!