This is something that has bugged me for a long time: how do people consider a "language reference" as a good documentation? Maybe it's because I'm not a programmer, so I'm not used to reading language references, but when I'm picking up a new language or a new tool, the most important things is to have examples on how to use the language to get things done. Take the unix manual for instance. The first thing I do when checking the manual is to search for example. Reading the list of switches is useless to me unless I have a working example of how the thing works.
So a good thing is a tutorial that guides people to the main parts of the language, explains the pitfalls, etc. I had to use mathematica to check some derivations about 6 months ago, and I spent a whole day trying to figure out how to work with it, and honestly, I nearly drowned under the documentation. There seems to be many ways to do the same thing (take the derivative of a function) and it is not always clear how/why should we use one method over the other.
Another problem I have with mathematica is that although the different functions are extensively referenced (I won't use the word documented), the language itself is not very well explained, and by language I mean how to piece all the functions together and more into one coherent piece of software.
Now I haven't spent enough time with it for my judgment to be definitive, but I found it harder to pick up than most languages / tools I've used.
i'm not sure what language you're talking about... the Mathematica Help docs are full of examples. check this Histogram page[1] and scroll down, check the Options section, Applications section, etc. that is a typical level of exemplification for a function like Histogram, and other functions are detailed as appropriate and the examples regularly showcase how to use various functions/functionality together.
i think what may have happened in your case is that you believed Mathematica was a math-specific tool (which it isn't) and so you didn't pay enough attention to the non-math aspects of the language, such as the basic API (for which there is replete documentation/examples in the Help docs, see for example [2]).
the most useful key in Mathematica is F1. click on anything, any symbol or function, and hit F1 to see the Help page for that item
"how do people consider a "language reference" as a good documentation?"
"when I'm picking up a new language or a new tool, the most important things is to have examples on how to use the language to get things done"
You look for different things when you think about how to implement the language. In a sense, the implementation doesn't really care about the use cases: it merely cares that the behavior matches the stated behavior in the documentation.
the IDEAL documentation for a developer is a proper PEG/LALR grammar for the language. That way you can properly parse expressions. Clearly they didnt provide it.
The documentation gives enough information to reduce an abstract expression from the GUI down to a mathematica expression, which is enough to build an AST. From there, it's a matter of building up each component to match the semantics.
"Another problem I have with mathematica is that although the different functions are extensively referenced (I won't use the word documented), the language itself is not very well explained, and by language I mean how to piece all the functions together and more into one coherent piece of software."
That's the job of the programmer. The documentation should explain how each bit works and the rules for combining the bits, but it's up to you to take the pieces and build something.
Think about Legos: you have a pile of bricks, and no one is going to tell you how to build a rocket ship using those pieces. That's up to you :)
"Take the unix manual for instance. The first thing I do when checking the manual is to search for example. Reading the list of switches is useless to me unless I have a working example of how the thing works."
The manpages do a poor job of explaining the zen of unix. Once you start thinking of operations as transforming streams of text, then you start thinking of tasks in terms of smaller units.
For example, a few minutes ago I needed a way to upgrade all global `npm` modules. I knew there was a way to get JSON lists (npm list -g --parseable --json), which lines I wanted (the ones starting with ' "'), and what I want to do with those (get the name and install). Putting it together, one straightforward way is
npm list -g --parseable --json 2>/dev/null | grep '^ "[a-z-]*": {' | sed 's/^ *"//;s/".*$//' | while read x; do sudo npm install -g $x; done
Now, the documentation doesn't explain that this is a way to do what I want. But the documentation gives enough information to know where to look.
So a good thing is a tutorial that guides people to the main parts of the language, explains the pitfalls, etc. I had to use mathematica to check some derivations about 6 months ago, and I spent a whole day trying to figure out how to work with it, and honestly, I nearly drowned under the documentation. There seems to be many ways to do the same thing (take the derivative of a function) and it is not always clear how/why should we use one method over the other.
Another problem I have with mathematica is that although the different functions are extensively referenced (I won't use the word documented), the language itself is not very well explained, and by language I mean how to piece all the functions together and more into one coherent piece of software.
Now I haven't spent enough time with it for my judgment to be definitive, but I found it harder to pick up than most languages / tools I've used.