5 ms·

Speaking as someone who writes blog posts littered with irrelevant pictures (but never on Medium!), I acknowledge your experience trying to solve a problem base

Speaking as someone who writes blog posts littered with irrelevant pictures (but never on Medium!), I acknowledge your experience trying to solve a problem based on a blog post. Manpages and documentation are written to be references. Blog posts are written to be tutorials. They have different affordances, and as a result it is very hard to learn how to use something purely from a reference, and very different to solve a problem purely from a tutorial. That’s why really decent reference sites have both step by-step tutorials AND references designed to answer questions quickly and to be easily searchable. If there is an opportunity here, it is for search to understand the difference and know how to present the two kinds of results differently. That way, if you question is, “How does this thing work?” You should get tutorials. If your question is much more specific, like “what parameters does this take?” You should get a reference. Or something hand-wave-y along those lines.

pteraspidomorph 7y ago
For js and js-adjacent technologies or libraries, there sometimes aren't any references to speak of, unfortunately. You're supposed to divine the information you need from task-oriented texts and code snippets.
- klez 7y ago
  Or, if you're using an obscure library, by reading the source code.
- braythwayt 7y ago
  Look, Sturgeon's Revelation is that "90% of everything s CRUD." That's true of almost every technology I've encountered in 45 years of programming. It's especially true when you lower the bar to entry. There's lots of CRUD because anybody can make something. It also means there are lots of things. If you want well-documented stuff, vote for it by not using things that are poorly documented. Or figure it out and write the documentation. That's how open source works (or doesn't work), and JS/Webdev is not unique in this regard. Microcomputers were poorly documented way back in the 70s. I'll be there were people complaining how shoddy they were on that basis, but that low barrier to entry led directly to us having this discussion on Hacker News today.
  - pteraspidomorph 7y ago
    If it's my decision to make, then yes, I'll do one of those things.
    - braythwayt 7y ago
      Of course you will, as do I. But it's no good moaning about the fact that they let just about anybody buy a computer and write software. That's literally why we're all here, because they let anybody buy a computer and write software, even people who can't be bothered to write documentation, or people who are too busy optimizing advertising click-through to give us good search results from a web browser. My thesis is that this is not limited to JS and WebDev, it's everything! It's just very visible with JS and WebDev. If there's anything in particular to focus on, I'd focus on package management. You pick something that seems well-documented, and next thing you know you have dozens or hundreds of other things baked into your app. If you go off the beaten path and need to break the abstraction of the thing you chose, you find yourself wrestling with the things that author chose.
- LandR 7y ago
  I'm a developer. When I work with most stuff that isn't web dev, life is good. I can figure most stuff out painlessly. It's mostly feels like working on a space that has been designed and documented by someone sane. When I'm forced to do Web dev type stuff... I want to jump off the roof. It always makes me question my life choices that led to me being exposed to js. I hate it, it's a logically incoherent disaster that feels like its been deigned by people who are all just winging it and sorely lacking a good CS degree. It all just feels immature and feels like it's a field trying to develop methadologies while ignoring lessons of the past and as a result making mistakes they shouldn't be. Once you get into this npm / node nonsense it feels like proper wild west madness. I'm sure it will mature some day. I'll probably be retired by then though. Then again maybe the entire eco system is doomed to a future of just constant nonsensical churn and the solution is just therapy or install nets on the tall buildings to catch devs, who after spending another day hating js, decide to junp off the roof! Another problem is I don't see many Web developers wanting to learn when they encounter something they don't understand, instead they just want some code they can copy and paste that had the illusion of solving their problem. Understanding be damned. Or even better a library, and hey if it has a million dependencies... Well.. That's life right?
  - mockingbirdy 7y ago
    > and sorely lacking a good CS degree Someone is speaking the truth here. But we (as a web dev I'll try to speak for us) are learning: React and Vue (and all the other great libraries) use optimized vdoms, React teaches functional programming paradigms with immutable data structures (redux) and we've already learnt from Ember what components we'll need in a project. Most people will simply follow blindly. After the base stops moving (breaking changes in the APIs - Vue is currently doing the last big ones), we will write the best practices. Every half-decently educated developer already understands that those ideas are not new. They are the same ones they've already had in the 60s. They will try to do it better - maybe they really are more clever, right? - but after the third or fourth try they'll understand that their own half-baked solution doesn't stand a chance. And then they will realize that life is too short to lose some data because your file-based DB implementation isn't ACID.
klez 7y ago
There's one particular case where a look at a reference is warranted: when something doesn't behave as expected. For example, the other day someone asked on stackoverflow why a particular Java class to calculate a difference between two dates was returning a weird result when they asked for the difference in days. Turns out, the class would calculate the difference in years AND months AND days, so if you asked for the difference between June 23 2018 and June 23 2019, the getDays method would return 0. While this is something you would find in a tutorial on how to calculate a difference between dates in Java, it's much more expedited to just go and read the reference. Works wonders when you get inconsistent results in C for example, since you're probably invoking undefined behavior which is documented in the standard (i.e., the reference). As a sort of counterpoint for this particular case, the documentation for that class didn't make how the class was meant to be used clear at all. But in the general case I think it applies.
- hermitdev 7y ago
  I haven't worked with Java much, but have done enough to have a thorough dislike of its built-in date libs. Trying to parse dates, for example, "2019-01-40" is accepted, and actually returns February 9, 2019. I'm not aware of Any other date lib that would accept this. The behavior was certainly surprising to me. Only found out because my QA guy at the time tried it, was also surprised by the result and filed a bug against one of my releases of a web service. Closed it out as won't fix.
  - onefuncman 7y ago
    this complaint is almost as old as the Java language. you should use Jodatime if you can't upgrade to Java 8+ yet -- see https://www.joda.org/joda-time/ https://www.joda.org/joda-time/
    - hermitdev 7y ago
      It also reminds of a quirk in DB2. I'm not sure if this is still the case, but in versions 6 and 7 circa 2003, '2019-06-24T24:00:00' and '2019-06-25T00:00:00' would never compare equal, yet they are the exact same point in time, excepting some rare leap seconds. Edit: spelling
antisemiotic 7y ago
This doesn't change the fact that irrelevant pictures (like memes and cheap popcultural references) belong neither in references nor blogposts, they're just a waste of time and bandwidth. Tone is a different matter, tutorials sure can be more lighthearted. But I'd still take a dry tutorial instead of forced, stillborn humor any day. (I'm not sure if the latter kind is all that common in the wild, could be an illusion of frequency on my part).
- braythwayt 7y ago
  As an author, that’s my decision to make about my blog posts. My choice of pictures belong in my blog posts, much as my choice of chords belong in my musical compositions. It’s a perfectly valid choice to write essays that are hyper-focused on just teaching the facts as efficiently as possible, but that isn’t some kind of universal rule that must be applied to all essays. I personally don’t care for the popular “American Folksy” style of essay that is heavy on the author’s journey to learn the thing it purports to teach, but I wouldn’t dictate that nobody should write in that style. There are no gatekeepers to writing words, just as there are no gatekeepers to writing code. That has its benefits, aand its hazards.
  - deleted 7y ago
    [deleted]
  - saurik 7y ago
    This seems orthogonal to the complaint: the person you are responding to is assuming you aren't just doing this because you think it is a worthy art form for your audience of people who enjoy it, but that you are attempting to write something that provides strong value to the reader. You are welcome to write whatever you want, but you are fooling yourself if you think it is helping. If you want a music analogy, you are welcome to make a movie score that has loud and clear lyrics while actors are talking... but I would still say to you that lyrics "have no place" in a movie score during a dialog scene--the audience is trying (and now failing) to hear the dialogue--even if there are some people who seem to enjoy that. So: you are welcome to write those tutorials in that style if you personally must--no one is saying they should be banned and censored and deleted from the web--and also you really should know that you are actively making a decision to be less useful.
usrusr 7y ago
> If there is an opportunity here, it is for search to understand the difference and know how to present the two kinds of results differently. Tag documents into categories (using ML diceroll, up to one category per document), with a strong bias towards "none" when in doubt. When a search term's results include some categories more frequently than the global average, offer them as filters. Would its utility survive the resulting wave of SEO innovations?
dirkt 7y ago
What is nearly always missing is some sort of overview that explains you which parts are there, what are they good for, and how they work together. Either these are very rare, or there are hard to google because they are drowned out by the many tutorials. When you follow a tutorial, you are shown a very specific way of doing things (which often isn't up to date, with no indication that in the meantime this way has been replaced by another way). And while that's very helpful for a beginner, it isn't as helpful for an experienced programmer, especially if he or she is having a problem that needs a slightly different way of doing things, and the missing information is just "instead of X, you can also do Y here". And references don't answer these questions, unless you work through them from top to bottom (which usually takes more time than you have).

pteraspidomorph 7y ago

For js and js-adjacent technologies or libraries, there sometimes aren't any references to speak of, unfortunately. You're supposed to divine the information you need from task-oriented texts and code snippets.

klez 7y ago
Or, if you're using an obscure library, by reading the source code.
braythwayt 7y ago
Look, Sturgeon's Revelation is that "90% of everything s CRUD." That's true of almost every technology I've encountered in 45 years of programming. It's especially true when you lower the bar to entry. There's lots of CRUD because anybody can make something. It also means there are lots of things. If you want well-documented stuff, vote for it by not using things that are poorly documented. Or figure it out and write the documentation. That's how open source works (or doesn't work), and JS/Webdev is not unique in this regard. Microcomputers were poorly documented way back in the 70s. I'll be there were people complaining how shoddy they were on that basis, but that low barrier to entry led directly to us having this discussion on Hacker News today.
- pteraspidomorph 7y ago
  If it's my decision to make, then yes, I'll do one of those things.
  - braythwayt 7y ago
    Of course you will, as do I. But it's no good moaning about the fact that they let just about anybody buy a computer and write software. That's literally why we're all here, because they let anybody buy a computer and write software, even people who can't be bothered to write documentation, or people who are too busy optimizing advertising click-through to give us good search results from a web browser. My thesis is that this is not limited to JS and WebDev, it's everything! It's just very visible with JS and WebDev. If there's anything in particular to focus on, I'd focus on package management. You pick something that seems well-documented, and next thing you know you have dozens or hundreds of other things baked into your app. If you go off the beaten path and need to break the abstraction of the thing you chose, you find yourself wrestling with the things that author chose.
LandR 7y ago
I'm a developer. When I work with most stuff that isn't web dev, life is good. I can figure most stuff out painlessly. It's mostly feels like working on a space that has been designed and documented by someone sane. When I'm forced to do Web dev type stuff... I want to jump off the roof. It always makes me question my life choices that led to me being exposed to js. I hate it, it's a logically incoherent disaster that feels like its been deigned by people who are all just winging it and sorely lacking a good CS degree. It all just feels immature and feels like it's a field trying to develop methadologies while ignoring lessons of the past and as a result making mistakes they shouldn't be. Once you get into this npm / node nonsense it feels like proper wild west madness. I'm sure it will mature some day. I'll probably be retired by then though. Then again maybe the entire eco system is doomed to a future of just constant nonsensical churn and the solution is just therapy or install nets on the tall buildings to catch devs, who after spending another day hating js, decide to junp off the roof! Another problem is I don't see many Web developers wanting to learn when they encounter something they don't understand, instead they just want some code they can copy and paste that had the illusion of solving their problem. Understanding be damned. Or even better a library, and hey if it has a million dependencies... Well.. That's life right?
- mockingbirdy 7y ago
  > and sorely lacking a good CS degree Someone is speaking the truth here. But we (as a web dev I'll try to speak for us) are learning: React and Vue (and all the other great libraries) use optimized vdoms, React teaches functional programming paradigms with immutable data structures (redux) and we've already learnt from Ember what components we'll need in a project. Most people will simply follow blindly. After the base stops moving (breaking changes in the APIs - Vue is currently doing the last big ones), we will write the best practices. Every half-decently educated developer already understands that those ideas are not new. They are the same ones they've already had in the 60s. They will try to do it better - maybe they really are more clever, right? - but after the third or fourth try they'll understand that their own half-baked solution doesn't stand a chance. And then they will realize that life is too short to lose some data because your file-based DB implementation isn't ACID.

klez 7y ago

There's one particular case where a look at a reference is warranted: when something doesn't behave as expected. For example, the other day someone asked on stackoverflow why a particular Java class to calculate a difference between two dates was returning a weird result when they asked for the difference in days. Turns out, the class would calculate the difference in years AND months AND days, so if you asked for the difference between June 23 2018 and June 23 2019, the getDays method would return 0. While this is something you would find in a tutorial on how to calculate a difference between dates in Java, it's much more expedited to just go and read the reference. Works wonders when you get inconsistent results in C for example, since you're probably invoking undefined behavior which is documented in the standard (i.e., the reference). As a sort of counterpoint for this particular case, the documentation for that class didn't make how the class was meant to be used clear at all. But in the general case I think it applies.

hermitdev 7y ago
I haven't worked with Java much, but have done enough to have a thorough dislike of its built-in date libs. Trying to parse dates, for example, "2019-01-40" is accepted, and actually returns February 9, 2019. I'm not aware of Any other date lib that would accept this. The behavior was certainly surprising to me. Only found out because my QA guy at the time tried it, was also surprised by the result and filed a bug against one of my releases of a web service. Closed it out as won't fix.
- onefuncman 7y ago
  this complaint is almost as old as the Java language. you should use Jodatime if you can't upgrade to Java 8+ yet -- see https://www.joda.org/joda-time/ https://www.joda.org/joda-time/
  - hermitdev 7y ago
    It also reminds of a quirk in DB2. I'm not sure if this is still the case, but in versions 6 and 7 circa 2003, '2019-06-24T24:00:00' and '2019-06-25T00:00:00' would never compare equal, yet they are the exact same point in time, excepting some rare leap seconds. Edit: spelling

antisemiotic 7y ago

This doesn't change the fact that irrelevant pictures (like memes and cheap popcultural references) belong neither in references nor blogposts, they're just a waste of time and bandwidth. Tone is a different matter, tutorials sure can be more lighthearted. But I'd still take a dry tutorial instead of forced, stillborn humor any day. (I'm not sure if the latter kind is all that common in the wild, could be an illusion of frequency on my part).

braythwayt 7y ago
As an author, that’s my decision to make about my blog posts. My choice of pictures belong in my blog posts, much as my choice of chords belong in my musical compositions. It’s a perfectly valid choice to write essays that are hyper-focused on just teaching the facts as efficiently as possible, but that isn’t some kind of universal rule that must be applied to all essays. I personally don’t care for the popular “American Folksy” style of essay that is heavy on the author’s journey to learn the thing it purports to teach, but I wouldn’t dictate that nobody should write in that style. There are no gatekeepers to writing words, just as there are no gatekeepers to writing code. That has its benefits, aand its hazards.
- deleted 7y ago
  [deleted]
- saurik 7y ago
  This seems orthogonal to the complaint: the person you are responding to is assuming you aren't just doing this because you think it is a worthy art form for your audience of people who enjoy it, but that you are attempting to write something that provides strong value to the reader. You are welcome to write whatever you want, but you are fooling yourself if you think it is helping. If you want a music analogy, you are welcome to make a movie score that has loud and clear lyrics while actors are talking... but I would still say to you that lyrics "have no place" in a movie score during a dialog scene--the audience is trying (and now failing) to hear the dialogue--even if there are some people who seem to enjoy that. So: you are welcome to write those tutorials in that style if you personally must--no one is saying they should be banned and censored and deleted from the web--and also you really should know that you are actively making a decision to be less useful.

usrusr 7y ago

> If there is an opportunity here, it is for search to understand the difference and know how to present the two kinds of results differently. Tag documents into categories (using ML diceroll, up to one category per document), with a strong bias towards "none" when in doubt. When a search term's results include some categories more frequently than the global average, offer them as filters. Would its utility survive the resulting wave of SEO innovations?

dirkt 7y ago

What is nearly always missing is some sort of overview that explains you which parts are there, what are they good for, and how they work together. Either these are very rare, or there are hard to google because they are drowned out by the many tutorials. When you follow a tutorial, you are shown a very specific way of doing things (which often isn't up to date, with no indication that in the meantime this way has been replaced by another way). And while that's very helpful for a beginner, it isn't as helpful for an experienced programmer, especially if he or she is having a problem that needs a slightly different way of doing things, and the missing information is just "instead of X, you can also do Y here". And references don't answer these questions, unless you work through them from top to bottom (which usually takes more time than you have).