3 ms·

>I don’t think I share your definition of “documentation”. Sorry for not being clear. I'm not attempting to redefine "documentation". I was answering the OP'

by jasode 8y ago

>I don’t think I share your definition of “documentation”. 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.

kd0amg 8y ago
I was replying that "contrarian and negative" type of information is an important supplement to "documentation" or even a higher priority than official documentation. But outsidetheparty already mentioned honest comparison with other work too, before bringing up documentation.
outsidetheparty 8y ago
OK, thanks for clarifying. 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.)

by jasode 8y ago

kd0amg 8y ago

I was replying that "contrarian and negative" type of information is an important supplement to "documentation" or even a higher priority than official documentation. But outsidetheparty already mentioned honest comparison with other work too, before bringing up documentation.

outsidetheparty 8y ago

OK, thanks for clarifying. 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.)