Sorry for not being clear. I'm not attempting to redefine "documentation".
I was answering the OP's main question: "What kind of _information_ do you look for before learning/using new tech?"
You had answered "documentation" as one of the pieces of information. I was replying that "contrarian and negative" type of information is an important supplement to "documentation" or even a higher priority than official documentation. (E.g. The contrarian perspective may highlight a showstopping issue which could override any need to even look at the official documentation.)
My hypothetical of "dream documentation" including negative info was a utopian fantasy for rhetorical entertainment. It was not a realistic prescription for authors of real documentation.
I don't tend to agree that contrarian / negative information is typically very useful as an indicator of the quality of a given piece of tech. There's no shortage of "Foo sucks" or "disadvantages of Foo" available for literally any value of Foo, and I rarely find them to be very useful; they generally feel like they're either written by someone who doesn't understand Foo very well, or who is evangelizing in favor of competitor product Bar. (Or, typically, both at once.)
I do of course agree that any product's inventors can be expected to be biased in favor of that product, and that pro-Foo material in itself is not a suitable sole source of information about Foo... which is why I said I weight so heavily in favor of products where the developers "acknowledge points where the competitor might have the advantage," and (in a different subthread) that I'm "assessing the quality of the tech based on the humility of the tech's inventors". It's also why I spend time looking at stackoverflow Q&A (watching people wrestle with their actual problems with a framework is much more illuminating than reading their rants about it afterwards.)
But outsidetheparty already mentioned honest comparison with other work too, before bringing up documentation.
Yes, it's technically easy but not socially easy. If I go to the Elixir landing page at "elixir-lang.org", it doesn't list the disadvantages and warts.
Obviously to us, they didn't avoid writing negative things because they ran out of disk space to store the text or didn't have the network bandwidth. The reason is that it's human nature not to do that. We have to find that alternative viewpoint from people like you (since you're interested in explicitly writing about some of Elixir's issues).
