Hacker News Reader

Comment by mxuribe | Hacker News Reader

Yeah for this statement, "...often Web developers are looking for quick examples...", I don't even care if the examples are higher up on the page or not...I just would like more and more examples. Sometimes the examples are too few or don't fully exemplify options of particular functions, etc. Nevertheless, I'm absolutely grateful to all the folks who put in so much work into MDN. If you are one of those people, know that I thank YOU!

View on HN

This is one of the only reasons I sometimes end up back at w3schools after reading the mdn docs: when I'm looking for a quick, working, live example. A short example is worth a thousand words.

This is the kind of attitude that leads to low quality, scrappy code, akin to copy and pasting Stackoverflow; I don't believe that a developer should need a great memory but they should have a good understanding which examples do not provide. I really like that the MDN docs are well specified and hope it stays that way.

That's an unnecessarily broad statement.

Nobody is arguing that we should be taking snippets and examples verbatim and use them 100% of the time without understanding them, just that there is value in having those snippets and examples available.

I know damn well how arrays work in javascript, from how they are implemented and what structures they use in memory at smaller sizes all the way up to the difference between a missing element in a sparse array to a dense array with an undefined value in it.

But sometimes I just want the snippet from MDN that "densifies" a sparse array. I know how it works, I can re-write it myself if needed, but I know that the one on MDN works and I won't hit any unexpected edge case because I forgot about some arcane bullshit thing.

Not to mention that when I'm first learning a new language or syntax I personally do MUCH better seeing examples of the code and being able to step through them to get the basics down (where I can then dive deeper into the system to understand the edge cases, hopefully with examples themselves to make sure I get the point).

> but I know that the one on MDN works and I won't hit any unexpected edge case

MDN is a wiki. People who want to contribute documentation or examples do so. Sometimes they make mistakes. Sometimes they're suffering from Dunning-Kruger. It is unreasonable to assume that the example will work and will not have unexpected edge cases.

It's the best resource I know on the web, which is I recommend it, and why I've contributed to it, but it's a wiki. Caveat emptor. (Caveat lector?)

An example functions as both a working piece of code, and also an illustration. I mean you might as well say ball-and-stick models are bad for chemists, because they should understand from the text alone.

There's a lot of technology to understand and absorb, and I'll take any tool I can get to help me.

APIs should be intuitive; they should be usable only from knowing their signature, and from having familiarity with similar functions. For the most part, DOM/WOM functions are like this, and so the doc will only be repeating things you could have derived intuitively. There are, of course, many situations where the use is non-obvious. In these cases it is even more important to have a good example demonstrating the idiosyncratic usage; a sidenote hidden away in the middle of the doc will easily be missed.

Examples are a great way to learn. Problems arise when they are the only way one learns.

exactly, MDN is great, but it's too "academic" for me, it's good for reference, however I admit the time I spent on w3schools is 100x more than it's on MDNs.

Yeah, it's a great resource. I'd love to see more examples as well. Bonus points if the examples are runnable and extra-bonus points if there's a 'debugger' version that would let the user jump into a portion of the code to examine the state.

I find one of the first things I do when approaching non-trivial new features is to sketch out an example and then step through the example by adding a few strategically placed breakpoints. The breakpoints allow me to examine both the execution flow and the internal state of the various objects associated with the new feature.

Both Chrome and FF support the handy 'debugger' statement, which you can place directly in your code and which acts as a breakpoint when you run the code with devtools open.

Edit: Apparently the debugger statement is standardized! Neat. Didn't realize that. Thanks MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...

> I just would like more and more examples.

I'd like relevant examples. It's incredibly frustrating to look at an MDN snippet to see code that no sane human would ever write. Self-executing closures that return callbacks inside for-in loops, initialization code that still checks readyState, code that avoids more than one function for no obvious reason...MDN can be a real crap-shoot. Hell, I'd be happy if they would name their variables sensible things instead of trash like `numFoo`.

That's why I love the Highcharts.js docs[1], which redirect to jsfiddle examples.

[1]http://api.highcharts.com/highcharts

Certainly there's room for more examples. Having to choose between often abstract MDN and the opposite - often zero theory Stack Overflow - is awful. I've learned to take SO with a dose of salt - you may pick up bad practices (especially for rare problems), outdated solutions etc.

> Sometimes the examples are too few or don't fully exemplify options of particular functions

TBH, that's why actual documentation is there. Examples can never really cover everything something can [or cannot] do.

An example is much more effective in a lot of cases. I really wish there were more of them in man pages.

It's a wiki. You can edit it!

Reply on news.ycombinator.com