Comment by jasode | Hacker News Reader

Comment by jasode | Hacker News Reader

Parent Full thread

>Is there documentation? Is it any good? This is a really low bar,

I definitely understand your reason for prioritizing documentation but I wanted to point out that "documentation" actually accomplishes the opposite of the OP's concerns about warts/disadvantages/gotchas/etc:

>, but also I want to describe stuff that I just hated or disliked. Because I've noticed that people always try to praise the new tech they are using, but rarely point out bad things.

As we know, documentation is typically written by people who are generally positive about the programming language or technology. Hoping for documentation authors to point out the flaws is like asking a mother to list the reasons her son is defective and girls shouldn't marry her.

To echo the specific issue the OP mentioned, my [totally unrealistic] dream documentation would be written by a crusty skeptical person that was an expert in the technology but became disillusioned by it. They'd point out all the flaws and pathological (but realistic) use cases where the technology fails or is inappropriate.

Since official documentation doesn't include the contrarian viewpoint, the newbies trying to evaluate new technology have to synthesize the "negatives" from other sources. E.g. I've typed the following phrases into google search:

  "golang sucks"
  "disadvantages of golang"
  "rust sucks"
  "disadvantages of rust"
  "disadvantages of python"
  "disadvantages of functional programming"
  "disadvantages of Linux"
  "disadvantages of <anything>"

It's the contrarian writing that helps us learn the limitations and tradeoffs of the technology. Do I search on "rust sucks" because I think Rust is bad?!? No. I search on that because that's the negative phrase that others might have used -- and I want to read their criticisms of Rust.

By all means, read the official and blessed documentation of the technology but be aware that it's a very biased viewpoint.

EDIT: added "[totally unrealistic]" to prevent misunderstanding of my point

Proper documentation, no matter who writes it, should cover how something works and what it does. Pros, cons, benefits and drawbacks are irrelevant here.

I want to know when method X of interface Y is called by the framework, with what parameters, and what it’s expected to return. This is a low bar that shockingly few software projects meet.

I don’t think I share your definition of “documentation”. I’m just talking about the “what does it do and how, what are the api calls and how do I call them” stuff. There’s no evangelism or bias there — or if there is, that’s certainly a hard strike against my perception of the product’s quality!

I think OP thinks about documentation of framework/language like an explanation of why/how/what for and not exactly API references. I agree with both of you, good API docs is mandatory, but also reading about advantages/disadvantages on the official website of given technology should be very easy to do.

>, but also reading about advantages/disadvantages on the official website of given technology should be very easy to do.

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).

Agree with you!

>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.

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.

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.)

It's the contrarian writing that helps us learn the limitations and tradeoffs of the technology.

I agree that evaluating the contrarian side is quite valuable, however both sides need to be taken with a grain of salt. I think that sometimes reading the negatives is more helpful, because people tend to be a little less careful in exposing their prejudices, or tend to be drawn to the more clickbait-y side. This makes the shallow criticisms more obvious, except for the cases where it manages to exploit your own prejudices.

Yes! And I’d like to add that a lack of such criticism just feels wrong. Like I’m researching into a cult instead of a tool.

Reply on news.ycombinator.com