Hacker News Reader

Comment by mintaka5 | Hacker News Reader

just for the record MDN's site, hands down, has the best documentation ever made by any agent of the programming industry

View on HN

It's not only a great reference documentation, it also has comprehensive guides for both beginners and advanced developers. Including niche/complex features like canvas, webrtc, service workers etc.

In a web programming course I created I often referred to and leaned on MDN.

Aside:

DDG lets you search in MDN directly if you prefix a search with !mdn. It's one of the few sites that has a very much usable search feature.

Kagi search also supports this bang shortcut, which I find very handy.

such a great resource and i have much respect for the devs of this site, to go to such a level quality, that it makes it easier for all of us to accomplish great things =)

Yet for some reason w3schools ranks higher in Google for many queries.

The exact reason why you need some control over your search engine results.

For me, I have blackholed w3schools and boosted MDN in my search engine of choice. It is quite nice to always get the MDN page on a web-dev related query as the top result.

Even searching for "w3schools" directly results in the wikipedia as the top result (which is.. fair enough).

The same search on DDG results is a page full of w3schools & subdomains.

Any reason not to mention which search engine you use?

I'm not him but Kagi supports this functionality, and I make heavy use of it. Incredibly useful.

To put the focus on the principle of controlling your search engine results, rather than the specific tool (which is Kagi btw)

Can also use a DDG bang: https://duckduckgo.com/bangs?q=mdn

Not the same, as I would then _only_ search MDN.

MDN does not know anything about the battle of waterloo:

https://developer.mozilla.org/en-US/search?q=battle+of+water...

And Wikipedia does not have any real API documentation of `requestAnimationFrame`

https://en.wikipedia.org/wiki/Special:Search?go=Go&search=re...

I want both of these to return sensible results for the bang-less search. This is the easiest for me and as a user of the search engine product, should also be what the search engine delivers me.

Using !mdn takes you to a mediocre-at-best MDN search page, not a specific page. My experience is that you’ll get better results from just adding the “mdn” keyword to the query and jumping to the first result—that is, instead of, say, `mix-blend-mode !mdn` (which takes you to https://developer.mozilla.org/en-US/search?q=mix-blend-mode), `mix-blend-mode mdn !` (which takes you to https://developer.mozilla.org/en-US/docs/Web/CSS/mix-blend-m...; the ! to skip the results page and go to the first match can be at the start or end of the entire query). This technique doesn’t guarantee you’ll end up on MDN, but for realistic queries you’re almost certain to.

I was telling a junior to avoid w3schools and use MDN, but I couldn't really give him a reason besides "everyone seems to hate it". What's the rationale for all the shade thrown at w3schools?

w3schools is a for-profit company that survives on its schooling business. Its incentives are mis-aligned with mine: When I search for information on something web-dev related, I want it to be short & to the point. For w3schools, to maximize paid lesson uptake, it needs to only superficially explain what I want to know, enough to leave me confused and willing to pay for lessons.

That is even assuming w3schools has accurate information, which historically they did not, and there is no reason why they will not lapse in this regard in the future.

MDN has better aligned incentives on other hand, if I can find the information I need quickly, then I can developer faster and higher quality websites, which in turn in the aggregate will benefit the participants in MDN who are incentivized to increase their respective browser penetration (etc., I don't want to get into a whole discussion here).

At some point you come to a level where approximately 0% of the w3schools pages contain the information you need, but 100% of the MDN pages. So.. why have the overhead of w3schools results? Also, why develop bad habits early on?

I'd say w3schools is actually much better for beginners than MDN. If you learn HTML, CSS or JavaScript, MDN will often include too much unimportant information. (Similar to how Wikipedia math articles are often inscrutable for beginners because they are littered with lots of advanced low-importance information.) Additionally, w3schools has more easy "try it" examples which MDN consideres too trivial to bother with.

I agree though that MDN is much better than w3schools for non-beginners.

https://www.w3fools.com/:

> When W3Fools was launched in 2011, the state of documentation for developers was poor. This site documented many content errors and issues with the W3Schools website. The Mozilla Developer Network was around but it did not have much support at the time.

> Today, W3Schools has largely resolved these issues and addressed the majority of the undersigned developers' concerns. For many beginners, W3Schools has structured tutorials and playgrounds that offer a decent learning experience. Do keep in mind: a more complete education will certainly include MDN and other reputable resources.

And the archived version where you can get a flavor of the specific content complaints: https://web.archive.org/web/20110412103745/http://w3fools.co...

There's 2 pretty reasonable reasons for this:

1. MDN's quality is higher, and it's more comprehensive when it comes to new browser specifications, but it's much less comprehensive in general technology/programming topics (e.g. W3Schools covers PHP which many working with e.g. Wordpress will dabble in alongside their HTML/CSS/JS).

2. Tenure. MDN's is much much more recent - W3Schools has been around forever.

W3Schools is a somewhat dodgy website with questionable quality, but it's hard to argue they've had a net-negative impact on educating programmers. I certainly learned a large chunk of my knowledge from W3Schools in the days before MDN docs existed in their current form.

I do found more minor errors in MDN compared to other official documentation (like Python), but it's kinda understandable.

And it sometimes takes months to get things fixed (after reporting or providing PR at https://github.com/mdn/content).

I've learned to always test myself when it comes to pesky/obscure behavior(s) of JS.

Thank you for sharing, feedback like this is a great to see :)

I disagree. It's very good. Far above average. But there's still a decent number of times I find missing details.

If we're talking the best then it has to compete with Qt, Rust, MSDN, cppreference, all of which I would say are better. Definitely in the top 10 though.

Then you haven't seen Rust's documentation yet.

https://doc.rust-lang.org/std/index.html

I'm partial to Elixir's documentation myself: https://hexdocs.pm/ecto/Ecto.html

Compare MDN's entry for the `map` method

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...

With Rust's

https://doc.rust-lang.org/std/iter/struct.Map.html

I find MDN to be a bit clearer, and they benefit from the in-browser runtime. All the extra detail in the Rust docs (blanket traits etc) were quite intimidating and distracting when I first started learning it.

That MDN page has a lot of noise and is not straight to the point. I guess that may be a side effect of JS though.

While both of these docs are pretty good, as someone who normally much prefers API references to "how to" formats, the MDN's "how to" approach here is succinct & just enough to cover reasonable bases, while the Rust API ref list is a bit too terse by comparison (& the Read More click out is a bit annoying).

Where's the noise? I'm not seeing any.

You linked to the docs for the result type of `map`, not`map` itself. The method is here:

https://doc.rust-lang.org/std/iter/trait.Iterator.html#metho...

The site is an absolute godsend, but it's also quite sad that the various standards specifications MDN covers have such terrible documentation websites of their own, that something like what MDN offers is even needed at all!

Just look at the official HTML and JavaSc.. nay, ECMAScript specification docs[0][1]. You'd sooner end up with a headache than a functional website if you had no other choice but to use those ;)

[0]: https://html.spec.whatwg.org/

[1]: https://262.ecma-international.org/14.0/

Those specs need to be extremely detailed to ensure interoperability. Earlier versions of the HTML specs were much more readable, but unfortunately lead to interoparability issues.

Someone put it like this recently: the audience for specs is browser vendors, and the audience for MDN is web developers; ideally, you shouldn't have to go to the specs if MDN describes the features well enough to get your application running or your problem solved. MDN docs consider the practical aspect of how application developers will use features or why they should care, so there is a need to keep the content accessible in as many ways as possible.

With full appreciation of all the complexities and intricacies involved here, the state of these official documentation resources as they exist today isn't great.

Additionally, most initiatives aimed at improving the situation have only resulted in yet more overhead in the form of additional committees with each their own agendas and procedures, or the creation of another new deeply interconnected but otherwise completely separate sibling standard[0][1][3][4], fragmenting things even further.

I used to be quite heavily involved with some of the more meritful of those initiatives, but at some point realised that despite all the time and effort I was putting in, nothing really meaningful/impactful had been achieved or was even anywhere in sight, and it was also becoming too costly on a personal level. Guess that's my justification for having the right to post this rant :)

[0] https://infra.spec.whatwg.org/

[1] https://webidl.spec.whatwg.org/

[2] https://w3c.github.io/html-aam/

[4] https://w3c.github.io/html-aria/

In some (rare) cases, I find that MDN doesn't have enough detail. Official specs aren't as easy, but I can usually track down any specific behavior detail in 10 or 15 minutes. For the degree of precision provided, I really think this is not bad at all.

The HTML Standard is excellent. It’s long and verbose because of the mountains of accumulated cruft it covers, so that it takes a little getting used to if you’re not familiar with the style, but it’s a magnificent document for finding specific answers in. I refer to it regularly, by choice, as a web developer and not a browser maker. There are large chunks of it that are really valuable reading for normal web developers. I still thoroughly appreciate MDN, but for HTML I could do without it without much trouble, the HTML Standard is good enough, even though it’s targeted primarily at implementers.

CSS specs are likewise very readable and extremely useful reference, though they’re less precise than significant parts of the HTML Standard. But if you have questions about how certain things fit together, or corner cases in certain properties, MDN is normally useless while the relevant specs are regularly invaluable. I highly recommend being familiar with reading these specs if you’re doing even mildly unconventional things.

The ECMAScript Language Specification: it’s not like either of the other two; it’s not a document that describes how things are supposed to act or how to use things, but is full code for implementing an ECMAScript engine—just expressed in natural language rather than a more accustomed programming language. I’ve referred to it a number of times when I’ve had nuanced questions about exactly what the engine does in such-and-such a case (the sort that the vast majority of web developers will never need or want to ask), and it’s been useful in such cases once it finally loaded, but it’s very firmly designed for implementers, not users. Covering any of the sort of stuff that MDN covers in documentation was never anywhere near the intended scope of the ECMAScript Language Specification, nor should it have been.

The specs and MDN serve quite different purposes, and something that combined both functions would be poor at both functions. Bemoan not the necessity of either: rejoice rather that you have both!

Especially considering they are facing an unusual hassle: browsers' compatibility (which is completely out of their control).

The quality of MDN gave me enough confidence to move away from frameworks and take matters into my own hands.

Reply on news.ycombinator.com