To be fair, the documentation does seem to have improved quite a bit with the 1.1 and 1.2 releases. My biggest problem with it has been snippets of examples in the query DSL sections with no clue as to where you put those snippets. Some examples now show full curl commands which is a huge improvement.