Comment by outsidetheparty | Hacker News Reader

Comment by outsidetheparty | Hacker News Reader

Parent Full thread

outsidetheparty

* Is there a clear reason the new tech exists? What differentiates it from its competitors? This alone rules out like 90% of new front-end web frameworks / widgets / plugins.

* Bonus points for tools whose authors have made the effort to explicitly compare it with competitor tools, particularly ones that acknowledge points where the competitor might have the advantage. ("Our new tech is better than existing old tech in every possible way" gets the side-eye from me; "Our new tech is better than existing old tech for these particular purposes, but old tech may still be more appropriate for these other purposes" goes a tremendous way towards confirming that the new tech has a real reason to exist.

* Is there documentation? Is it any good? This is a really low bar, but far too many new tools have no documentation at all ("just check out the source code") or have minimal, incomplete, or tautological docs ("bar.foo(): executes the foo method of bar"). A message board or IRC channel is nice, but not a substitute.

* How big is the API surface? Does it need to be that big? I tend to avoid tools where there are six different ways to do the same thing -- looking at you, Angular -- it suggests the developers are unfocused or in disagreement, and makes it harder to find support or documentation on any particular issue. Same thing if the API has undergone major breaking changes or paradigm shifts between versions (looking at you, Angular...)

* What does the tag look like on stackoverflow? This serves as a good indicator of whether the tech is too new or obscure to bother with, what the common pain points are, the average skill/knowledge level of its users, and whether help will be available if I get stuck when using it.

* Is there a relatively simple way to try it out? I'm much more likely to experiment with something where I can clone a repo and get going with simple but nontrivial example code; if I have to reconfigure half the settings on my machine just to get a hello world, I'm not going to bother.

Ya know...this - along with other answers - is a product waiting to happen. Kinda like Product Hunt (I suppose) but with particular Q&A crowdsourced so everyone can get a clear non-marketing spun picture of a given product.

Maybe?

Maaaaaaybe. It's really hard to get objective information about this stuff -- people naturally tend to evangelize the tools they already understand, and discredit the ones they don't -- which would make crowdsourcing this kind of info a real challenge. The inventor of tool Foo saying "Foo is good for this but not good for that" signifies much more to me than Random User of tool Foo saying the same thing.

Oddly enough, as I'm rereading through my own list I'm just now noticing how many of them really boil down to assessing the quality of the tech based on the humility of the tech's inventors: if they understand that their code isn't self-explanatory, and that good documentation is important, and that it isn't necessarily perfect for everything just because they invented it, then that implies a lot more care and deliberation in the code itself.

Oh yeah. There's some friction that needs to be addressed. No kidding :) However, we ALL suffer (more) from the pain(s) of not having good information, to say nothing of all the aggregate time wasted testing products because we have no other choice.

I think if there was (kinda sorta) a crowdsourced FAQ that might work. Kinda like you see on e-comm sites in that someone asks a question - aside from some boilerplate questions (e.g., your list) and others can answer. Spammy questions (and answers) can be down voted (a la HN).

Again...Maybe? :)

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

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

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.

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!

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.

So you have this list written, and whenever you encounter a new technology you run it by it?

Or you just imagined your ideal choosing process?

Or perhaps you use what you employer's previous employee chose to use.

These are the sort of thing I tend to ask myself when considering whether to use a new piece of tech, yes. Obviously when I'm working with a company that's already made a technology decision, I'm going to follow that decision unless there's a really compelling reason to start over with something new.

Reply on news.ycombinator.com