[jim-jim-jim]

One of the things I don't like about webdev (among many) is that I even have to Google in the first place. Manpages are so much more immediate and accessible.

I also think that anything js-adjacent has a real culture problem. Trying to dredge an answer out of a Medium tutorial written in a cloying tone and interspersed with pointless gifs can be such a groan enducing experience. I'm hoping that the community will mature alongside its technology.

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

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

[markbnj]

> One of the things I don't like about webdev (among many) is that I even have to Google in the first place. Manpages are so much more immediate and accessible.

I don't really get this response. First there's the notion that "webdev" is the discipline where information is so fractured that you need to go googling around to figure out how to do everything. All the other disciplines have a magic thing called a man page that just gives you the answers. This is obviously not true, right?

The second thing is the idea that a man page for any one component, or even a set of components, could possibly contain enough information to allow you to build a complex system without consulting the experience of peers, colleagues and past practitioners, which is at least what we intend to do when we search google.

[username90]

> All the other disciplines have a magic thing called a man page that just gives you the answers. This is obviously not true, right?

It is true to some extent. The less dependencies you have the less you need Google. Have thousands of dependencies in node? You will likely google their different error messages a lot. Write low level C libraries where not having dependencies is a key feature? Then Google wont help you much at all, the few times I try I almost never find anything useful for my work.

So the thing about web dev is that you automatically have all browsers as dependencies, not to mention all the libraries, frameworks and api's people are using in modern webdev workflows. Most other fields tend to have much simpler dependencies than that.

[tenaciousDaniel]

Also the "manpage" does exist - it's the spec. But I've never met a single person who has ever directly read it.

[RussianCow]

MDN does a pretty good job of distilling the web spec into readable documentation: https://developer.mozilla.org/en-US/

[mgkimsal]

it's so 'readable' that a friend of mine is... reading it. Out loud. In to Soundcloud. (well, JS stuff anyway).

https://soundcloud.com/user-956222694

[err4nt]

I'm in the HTML specs and CSS specs every day :D

- https://html.spec.whatwg.org/multipage/

- https://drafts.csswg.org/

[Retric]

Reading web specs at least once will save you a lot of time. You don’t need to memorize the things, but it helps learning about capabilities that are easy to miss and keywords that’s make searching far more efficient.

[bryanrasmussen]

I used to read the specs, but I think I gave that up about 15 years ago as no longer practical.

[megaremote]

> But I've never met a single person who has ever directly read it.

I love how this is a unit of measure now. "I have never met anyone with an iphone, so...".

[snazz]

Man pages rarely are enough in my experience. When I encounter an issue with grub-install not writing to my EFI system partition, good luck finding much about it in its very short man page. You’ll have better luck using the ArchWiki, which is like a much better man page, but a simple Google search (or another search engine) will show a forum post with an easy solution as the very first result.

Piping six man pages through grep to find what I’m looking for is simply not as fast as Googling an error message.

I think there’s also a sort of cultural difference between languages and tools frequented by newer and older programmers: more experienced people look for documentation and then get working on their project, whereas less experienced programmers look for tutorials and very specific “soft” documentation.

Transitioning from modifying tutorials (the type-in-the-code-in-the-magazine of the 21st century) to glancing at the documentation is probably the surest sign of maturity. Still, you can get a ton done by copypasta.

This might have to do with learning to code with or without the Internet, I’m not sure. I’m personally very envious of people who can take a look at the docs and just get chopping without the assistance of the GIF-covered Medium posts.

[klez]

> When I encounter an issue with grub-install not writing to my EFI system partition, good luck finding much about it in its very short man page

This says more about the man pages for grub2 (and grub2 itself, to be honest) EDIT: than about manpages /EDIT.

Compare them with the man pages for grub1. There's a sea of difference.

If you really want to be blown away by a manpage, look for the one for mplayer, which is difficult to find information in for different reasons, i.e., lots of options and lots of options and flags that depend on other flags and options.

[umanwizard]

Yet another reason to prefer the BSD family of OSes over the GNU/Linux family.

In the BSDs, self-contained, complete, and correct documentation is a cultural value. Not one that’s always achieved, but a value nonetheless. Information missing from the man pages is a reportable bug.

And if the man page doesn’t document something, its code is right there in /usr/src for you to dig into.

[jnbiche]

Agreed. Even in Linux, complete documentation for userland tools is usually a given.

Not so with webdev. That said, the source code is there for all of us to read. I'm a frontend developer and spend more time looking at source code when I need to figure out an issue than digging through Medium posts. Particularly when something is behaving in an unexpected manner.

I'd urge everyone who hates webdev to try this approach the next time they struggle with an issue. JavaScript, for all its sins, is fairly easy to read. And once you've understood the ~30 most common gotchas in JS, reading the source is highly beneficial (and here's a good intro to those gotchas, including an accompanying video: https://github.com/denysdovhan/wtfjs)

Or better yet, work in one of the statically-typed compile-to-JS languages such as Typescript, ReasonML, Elm, ScalaJS, or Purescript and worry about those gotchas much less (and only when wrapping external libraries).

[baroffoos]

I find manpages to be mostly useless because they ignore the common case to explain every single possible function. For example I use the tar command 99% of the time for extracting files and 1% of the time compressing files. When I open the manual I want to be able to quickly work out how to extract a file but the first bit of non intro text on the man page is

>Options to GNU tar can be given in three different styles. In traditional style, the first argument is a cluster of option letters and all subsequent arguments supply arguments to those options that require them. The arguments are read in the same order as the option letters. Any command line words that remain after all options has been processed are treated as non-optional arguments: file or archive member names. For example, the c option requires creating the archive, the v option requests the verbose operation, and the f option takes an argument that sets the name of the archive to operate upon. The following command, written in the traditional style, instructs tar to store all files from the directory /etc into the archive file etc.tar verbosely listing the files being archived:

Scanning through the manpage a fair way down and I can't see the one bit info that covers almost all of my use cases for tar.

And for anything more complex than a tiny cli tool the manpage is far too large to use usefully.

[detaro]

For the specific example of tar, the EXAMPLES section of the man page covers what I typically need, but that's not true for all man pages.

[baroffoos]

For some reason my copy of the tar manpage on fedora has no examples section

[em-bee]

but there is a dozen ways to compress files, and only one way to extract them (for each compression format). i need the tar manpage much more when i compress, and rarely when i decompress.

[your-nanny]

one of the very first thing in tar's man page is an example of how to extract a file: https://linux.die.net/man/1/tar

but what evs. sometimes the man page is the thing, sometimes not.

[tasuki]

TLDR pages (https://github.com/tldr-pages/tldr) are nice exactly for this use case.

There's also a web interface, for tar that'd be: https://tldr.ostera.io/tar

[awinder]

I’d honestly love to know what people are comparing to javascript when they complain about rate of change / having to learn, unless it’s just a mental bias on learning something new vs something they’re comfortable with. I’m in a new position working on python and spring APIs and it’s effectively the same deal — researching means filtering through bitrotted methods and advice over a 4-5 year period, new methods & libraries or api usage patterns, etc.

Anyone could divine some reasons for why javascript / “web dev” is so different but I’m seeing shades of the same thing mixed with personal biases towards trade offs and design decisions.

[MarkMc]

I've been programming mostly in Java for 20 years, and in the past whenever I picked up web development it always felt like a kludge. JavaScript was inferior to Java, CSS was frustratingly difficulty to lay out components, and HTML forced me to treat my application like a printable document. Tools and libraries weren't as efficient or robust. Then I had to test on 5 different OS/browser combinations and implement ugly workarounds to fix the inevitable discrepancies between platforms.

Recently I've been developing in Flutter/Dart, and it's so enjoyable. The Dart language is an improvement on Java, the Flutter documentation and online support is great, apps look and behave the same on different devices, the API and underlying code is well designed. Plus the tooling and IDE integration is first-class.

[umanwizard]

In general it seems like most native C++ software has far fewer external dependencies than JS software does. Not zero, of course, but culturally people are much more reticent to take a third-party dependency than they are with JS.

Perhaps this is because it is just so much less of a hassle to do so in a world with things like NPM.

[klez]

Try C. You can find stuff from 20 years ago and it's still mostly relevant. Or at least applicable.

[awinder]

This is what I’m talking about with this argument being a proxy against learning vs a legitimate difference. I just replaced a big chunk of a 20 year old C system this year. There was nothing even researchable in there because the vast majority was homegrown, or libraries were pulled in and source-modified after going stagnant on the 20 year journey. Same exact symptoms I’ve seen in every other ecosystem.

[BossingAround]

What you're mentioning is all just a side effect of something being extremely accessible. Webdev is very easy to start and get into, but on the deep end, it's just as deep and difficult as coding a backend of your application in Java or Go.

You don't have to search the internet for web dev any more than you have to do so for any other dev job.

[jimmaswell]

Man page: find the man page, search for terms you hope might be related to what you want, read through a lot of dense paragraphs to maybe find something relevant.

Google: just type in a quick description of your issue and get a stackoverflow post with an answer as the first result.

I don't get how anyone could prefer the man page.

[umanwizard]

For me the issue is not really whether I access the docs through `man` or through the browser. It’s comprehensive, accurate docs provided in one place by the vendor of the tool I’m using, versus wading through a crowdsourced resource like SO which might be incomplete, out of date, or inaccurate.

If a library vendor provides good docs on their website, that’s just as good as man pages, but in my experience they usually don’t.

There is a staggering amount of misinformation or non-existent information on Stack Overflow. For one simple example: try to figure out how to use the GPS on iPhone. It’s simply impossible. 99% of people on SO think “GPS” is synonymous with “Location APIs” in general. Of the 1% of people who understand the several different data sources used by CoreLocation, nobody can tell you which accuracy settings will cause it to use GPS specifically. If you bother asking, you’ll get a bunch of “middle-brow dismissals” asking why you want to know such a thing, telling you to just use whatever accuracy setting you semantically need, smugly claiming you’re guilty of posing an A-B question, and so on. This is the type of dead simple basic information I would have expected to be present in Apple’s documentation, instead of having to crowdsource it from internet trolls.

[Theodores]

Stack Overflow has a problem of outdated answers written ten years ago by people wanting to collect experience points.

Technology moves on and those early answers are simply no good. Recently I decided to learn a few things from first principles - reading the specs. If I then try to put a half decent answer on SO then it will be answer 97, 3563 upvotes behind the 'right answer'.

New person who comes along isn't going to get to my detailed answer on page 5, the one that points out how technology has moved on and why the winning answers are not what you needed. They just need to deliver the deliverables and the first answer will suffice. They will take it and add another plus to the upvotes.

You can't win, the odds are stacked in favour of the mediocre. This wasn't always the way with Stack Overflow, in fact it replaced forums where the same problem existed but only to stall the nonsense for a few years, we are back to peak nonsense again.

I think time is ripe for Stack Overflow to be usurped, nothing against the site which I have so loved over the years, but even mySpace had to be replaced by Facebook.

[baroffoos]

Stack overflow doesn't need to be replaced they just need to find a way of filtering out answers that are no good anymore which is actually a bit of a hard task because many ancient answers about vim and git are still perfectly valid.

Maybe some kind of super downvote for outdated questions that is strictly moderated so it isn't abused.

[umanwizard]

I completely agree that this is a serious problem. But I’m not sure how it could be solved, and I still think vendors providing docs, and easily readable source code for when the docs fail, is a necessary complement to any crowd-sourced model, be it forums, SO, or anything you might imagine replacing SO with.

[jimmaswell]

This is basically never been the case for me. Once or twice I got an answer that suggested a deprecated API call, which I could then just google the replacement for and use that. I don't have any complaint about StackOverflow personally.

[Theodores]

If you are on the bleeding edge of the new shiny then you won't have this problem that I am seeing. But the guy supporting your code in five years time might.

To some extent the problem depends on how new and shiny your stuff is.

[jimmaswell]

My experience has been the same ranging from questions about C, C#, JS, Python, and many others.

[lazerwalker]

Do you personally have recs for how to parse manpages? In my experience, I've found them far more difficult to grok than e.g. the MDN JavaScript docs. Particularly if I'm trying to look up a tool that I don't already have familiarity with, as opposed to e.g. just trying to look up the correct syntax for a flag.

[hombre_fatal]

Yeah, manpages feel like the equivalent of being served a book on a subject where I just want to know a quick incantation. Like reading the entire wikipedia entry on cats just to settle a dispute on how many toes they have (18 btw).

I think manpages are a popular thing to worship here for nerd points but people don't use them nearly as much as they say they do because nobody actually wants to read a manual when they are trying to Get Things Done. Also, some things are just incredibly hard to figure out, like ffmpeg arguments.

Check out http://bropages.org/

[flukus]

> Yeah, manpages feel like the equivalent of being served a book on a subject where I just want to know a quick incantation.

Because manpages are from a time when reading the manual was expected behavior, searching for a quick incantation more often than not results in learned helplessness because you don't actually learn anything, just the specific spell for the specific situation.

I'm as guilty as anyone of trying to solve the immediate problem with a magic spell at times, but bropages embrace this willful ignorance.

[your-nanny]

not to make fun of my old roommate, but I had to give him line by line instructions for him to use a scientific calculator, which he dutifully copied, instead of taking the time to learn calculator principles. know your tools.

[anthk]

Bro pages are a joke compared to the conciseness of man pages under OpenBSD.

[andreareina]

Except for being an online resource, the MDN docs are much more like man pages than what the parent is talking about.

Btw if you find the MDN search unsatisfactory (as I do) try mdn.io/search term. It's just a proxy for site:developer.mozilla.org search term + I'm Feeling Lucky.

Edit: https://github.com/lazd/mdn.io

[bobthepanda]

The MDN is a pretty good reference complete with availability tables for browsers.

The problem with a reference is that a lot of times browsers do quirky things and things that are essentially browser-specific bugs aren’t documented in a reference.

[MaxBarraclough]

> I'm hoping that the community will mature alongside its technology.

Which technology? Web development frameworks seem to have a half-life of about 12 months. 'Mature' and 'obsolete' are near synonymous.

[jhoh]

> Web development frameworks seem to have a half-life of about 12 months.

Initial realeases of the most popular JS-frameworks:

Angular – 2010

React – 2013

Vue – 2014

[MaxBarraclough]

Polymer 0.5 - circa 2014 Polymer 1 - 2015 Polymer 2 - 2017 Polymer 3 - 2018 LitElement - 2019

(I'm aware that Polymer insists it isn't a 'framework'. But it is. If their breaking changes cause incompatibilities between components using different Polymer versions, that's what I call a 'framework'.)

[MaxBarraclough]

*also the ~recent deprecation of Bower

[Pxtl]

Angular doesn't count as 2010 because they did massive compatibility breaking change to Angular2 such that it was basically a new framework.

[deiznof]

This really just isn't true about the javascript scene anymore, and hasn't been for a little while now. React and Angular alone make up the vast majority of framework usage and they've been out for years.

Honestly, a lot of javascript criticism I see nowadays is a little outdated.

[MaxBarraclough]

> This really just isn't true about the javascript scene anymore

Still looks true to me. I gave the example of Polymer in my other comment.

[CondensedBrain]

https://devdocs.io/ isn't exactly equivalent to manpages, but works well enough. You can even download documentation for offline use.

[rzzzt]

Thank you for posting this! Parent's comment reminded me of this page, but couldn't remember the URL...

[onion2k]

You can access MDN as man pages - https://github.com/rafaelrinaldi/mdn

[noir_lord]

Couldn't agree more.

All that and emojii's sprinkled everywhere like cat vomit.

[DonHopkins]

I hope you're not advocating writing documentation in troff instead of html!

[hiccuphippo]

It would be very nice if the whole MDN could be downloaded as man pages or even just html pages with some form of local search.

[bdcravens]

I feel this is less the case than it was a few years ago, but a lot of the same complaints can apply to the Rails ecosystem.

[kyriakos]

the worst kind is youtube tutorials disguised as blog posts. you open the link, there's 5 lines of intro and then an embedded video.

and I hate videos cause usually skimming through text you can get to the part you want to read quickly but with videos you need to go through it