3 ms·

I'm curious if the issue with "lacking documentation" is an issue with explaining function inputs and outputs (like types would give you in other languages), ex

I'm curious if the issue with "lacking documentation" is an issue with explaining function inputs and outputs (like types would give you in other languages), expected behavior, or just bad discoverability for the long list of core functions. When I was starting, I ended up just learning to read the function source because of the lacking documentation. It's a skill that has paid off in the end, but i'm not sure it was the best way.

pchristensen 13y ago
"bad discoverability for the long list of core functions." IMO it's this and discoverability of libraries for non-core functionality. The books for learning Clojure are all very good, but reading a book is a lot different than working down a tutorial.
- puredanger 13y ago
  I think the new O'Reilly Clojure Cookbook (also available at https://github.com/clojure-cookbook/clojure-cookbook https://github.com/clojure-cookbook/clojure-cookbook ) will be a hugely important resource in this area.
  - gtani 13y ago
    Thanks, didn't know about that (the 4 books from Oreilly, Manning and Pragmatic are all terrific). Another thing is if getclojure could get some pruning and discussion of corner/edge cases for each core function/macro/special forms (i.e. get some of the discussion from IRC of how/when to use the functions and maybe make it more hoogle-like) http://getclojure.org/search?q=conj&num=0 http://getclojure.org/search?q=conj&num=0
puredanger 13y ago
Did you use http://clojure.org/cheatsheet http://clojure.org/cheatsheet ? I think it's helpful for discoverability.
- jared314 13y ago
  I eventually found the cheatsheet and it remains useful to this day. But, my specific point was trying to dissect what survey respondents were looking for when asking for more documentation, because each item I listed has a different possible solution. Documenting function inputs and outputs could use core.typed's annotations to enhance the docs. Documenting expected behavior leans towards adding content and examples, where the examples can be manually curated or pulled from available opensource code. (Similar to getclojure.org, but bigger.) Solving bad discovery could be approached by improving the search/organization/unification of the clojure.github.io, the cheatsheet, clojuredocs.org, clojure-toolbox.org and clojure-doc.org. So, what did they want exactly?
  - puredanger 13y ago
    Totally agreed on the question. I have been trying to engage people more actively in the details of this question as well. There are actually many, many documentation resources right now (seemingly enough for anyone to get started), so the question is really whether actual docs are lacking or just the right place(s) to start for specific kinds of docs.

pchristensen 13y ago

"bad discoverability for the long list of core functions." IMO it's this and discoverability of libraries for non-core functionality. The books for learning Clojure are all very good, but reading a book is a lot different than working down a tutorial.

puredanger 13y ago
I think the new O'Reilly Clojure Cookbook (also available at https://github.com/clojure-cookbook/clojure-cookbook https://github.com/clojure-cookbook/clojure-cookbook ) will be a hugely important resource in this area.
- gtani 13y ago
  Thanks, didn't know about that (the 4 books from Oreilly, Manning and Pragmatic are all terrific). Another thing is if getclojure could get some pruning and discussion of corner/edge cases for each core function/macro/special forms (i.e. get some of the discussion from IRC of how/when to use the functions and maybe make it more hoogle-like) http://getclojure.org/search?q=conj&num=0 http://getclojure.org/search?q=conj&num=0

puredanger 13y ago

Did you use http://clojure.org/cheatsheet http://clojure.org/cheatsheet ? I think it's helpful for discoverability.

jared314 13y ago
I eventually found the cheatsheet and it remains useful to this day. But, my specific point was trying to dissect what survey respondents were looking for when asking for more documentation, because each item I listed has a different possible solution. Documenting function inputs and outputs could use core.typed's annotations to enhance the docs. Documenting expected behavior leans towards adding content and examples, where the examples can be manually curated or pulled from available opensource code. (Similar to getclojure.org, but bigger.) Solving bad discovery could be approached by improving the search/organization/unification of the clojure.github.io, the cheatsheet, clojuredocs.org, clojure-toolbox.org and clojure-doc.org. So, what did they want exactly?
- puredanger 13y ago
  Totally agreed on the question. I have been trying to engage people more actively in the details of this question as well. There are actually many, many documentation resources right now (seemingly enough for anyone to get started), so the question is really whether actual docs are lacking or just the right place(s) to start for specific kinds of docs.