[braythwayt]

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.

[klez]

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]

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]

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/

[hermitdev]

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

[cafard]

JavaScript on Chrome and Firefox will accept days up to 31, regardless of month--'9/31/2019' will be October 1. On the other hand, IE 11 really doesn't care how big the day is--100, 1000, it's all good. "new Date('6/1000/2019') is Feb 24 2022 as far as IE 11 is concerned.

[mgkimsal]

wow - replace 'java' with 'mysql' and you've got one those decades-old go-to arguments against mysql. Except... the anti-mysql crowd would always point to it with the implication that somehow it was the only "wrong" behavior in the computing universe. I had no idea Java behaved that way too.

[bobthepanda]

The problem with webdev is that JS has a lot less "standard" than other languages like Java, so a lot of times people either reinvent the wheel or import some package to deal with things that would be standard in a language like Java, and they implement things their own way.

The other problem is that you're not really fighting JS or CSS or HTML per se, but a browser implementation of interpreters for that. And you don't really have a say in the matter, because you're not picking what browsers are using your webapp, your users are. This is only really solvable using a combination of MDN, Stack Overflow, and Google-fu.

[dirkt]

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]

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.

[LandR]

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]

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

[braythwayt]

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]

If it's my decision to make, then yes, I'll do one of those things.

[braythwayt]

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.

[klez]

Or, if you're using an obscure library, by reading the source code.

[antisemiotic]

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]

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.

[saurik]

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.

[braythwayt]

"Useful" is very much context-dependent. A post that does not catch the reader's attention is not useful. If you write in a style that is indistinguishable from a thousand other authors writing about the same topic, your writing is equally useless.

It is a mistake to think that an "audience" is one uniform set of people with identical needs, tastes, and interests. And therefore it is a mistake to suggest that there is something inherently "less useful" about one style of writing over another.

Less useful for whom? Under what circumstances?

I agree 100% that if you define your audience as "person trying to solve a problem and googling for help," my writing is terribly useless.

But I don't write for that person under those circumstances, and I assure you that the pictures in my blog posts do not bleed over to obscure any of the text.

I personally think that analogy doesn't really fit. A different take might be to consider Raymond Smullyan writing about combinatory logic.

If you just want to solve a homework problem, reading "To Mock a Mockingbird" is going to be an exercise in frustration. What's all this faffing about with birds and forests? Or locks and vaults?

Nevertheless, a great many people have found the book both useful and entertaining, which is a kind of useful in its own right. Smullyan also knew that there were other ways to write, and he wrote textbooks that eschewed the metaphors and entertainment while focusing on the utility.

---

I am not fooling myself that my writing is helping some people, some of the time. I know that it does, and I have the data to prove it. But, I am also not fooling myself that what I write is the best thing for all people under all circumstances.

I regularly endorse buying books like Eloquent JavaScript or You Don't Know JavaScript precisely because they are written in a manner that is useful in a different way than my own writing is useful.

But getting back to the subject of the post... I think that ultimately, search should be sure to highlight StackOverflow and MDN results or similar. Reference works designed to answer questions simply and directly are what you need when you're in the middle of a problem.

Blog posts serve a different purpose, such as motivating you to want to solve the problem in the first place.

[antisemiotic]

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

Of course, just like anyone's free to say "it's a generic 4:4 I–V–vi–IV pop song, nothing to write home about" or "it's yet another ISO standard blogpost, don't bother clicking through the popup". Though I think a better equivalent of a meme-laden blogpost would be a sea-shanty with changing time signatures and atonal riffs with a rabid scene kid at the vocals - kind of bizzare, kind of crass, fully useless for pulling a rope on a galleon.

>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 wasn't arguing that every blogpost should be hyper-focused, just that it would be kind of nice if more people took the route of "uncreative but solid" rather than "trying to create an illusion of creativity with randomness".

[javajosh]

> "trying to create an illusion of creativity with randomness"

I doubt that's why authors use this technique, though. I think it's part humble-brag ("hey I'm so smart I don't take complexity seriously!") and part an expression of nervousness ("it's scary to write things and publish on the internet, because haters"). A less serious style also allows you to take criticism more easily, perhaps.

That's an explanation, not an excuse! I like dense, solid prose more.

[antisemiotic]

Hmm you're right, on a related note patching holes in my understanding of a topic with "distance" and sarcasm is something I'm personally guilty of. I'm grateful of HN for being much less conductive for that style than, say, Reddit.

[braythwayt]

I think a better equivalent of a meme-laden blogpost would be a sea-shanty with changing time signatures and atonal riffs with a rabid scene kid at the vocals - kind of bizzare, kind of crass, fully useless for pulling a rope on a galleon.

To my great delight, this phrase illustrates the value of writing with feeling and metaphor. It captures my imagination and motivates me to think about your argument carefully.

[antisemiotic]

I've never argued that metaphors make for worse technical writing. It's just that you've started the discussion defending putting random pics into a blog post, and now you're trying to paint opposition to these as an opposition to creative technical writing (vide the sibling post about Raymond Smullyan). I think we might be in a violent agreement here, actually.

[braythwayt]

+1

[vikramkr]

Why don't they belong in blog posts? They belong anywhere the author had made the creative decision to include them, and if you don't like it, that's fine, but if the author wants to use their time and bandwidth in the article to post irrelevant memes then that's their call. To you it might be a waste of time, but in general people can and should do whatever they want.

[usrusr]

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