6 ms·

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

raincole 3y ago
Especially considering they are facing an unusual hassle: browsers' compatibility (which is completely out of their control).
bsmth 3y ago
Thank you for sharing, feedback like this is a great to see :)
dgb23 3y ago
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.
- edlucas 3y ago
  Kagi search also supports this bang shortcut, which I find very handy.
- mintaka5 3y ago
  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 =)
krono 3y ago
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/ https://html.spec.whatwg.org/ [1]: https://262.ecma-international.org/14.0/ https://262.ecma-international.org/14.0/
- bazoom42 3y ago
  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.
  - bsmth 3y ago
    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.
  - krono 3y ago
    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/ https://infra.spec.whatwg.org/ [1] https://webidl.spec.whatwg.org/ https://webidl.spec.whatwg.org/ [2] https://w3c.github.io/html-aam/ https://w3c.github.io/html-aam/ [4] https://w3c.github.io/html-aria/ https://w3c.github.io/html-aria/
- recursive 3y ago
  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.
thrdbndndn 3y ago
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 https://github.com/mdn/content). I've learned to always test myself when it comes to pesky/obscure behavior(s) of JS.
Xenoamorphous 3y ago
Yet for some reason w3schools ranks higher in Google for many queries.
- Phemist 3y ago
  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.
  - hju22_-3 3y ago
    Any reason not to mention which search engine you use?
    - leadingthenet 3y ago
      I'm not him but Kagi supports this functionality, and I make heavy use of it. Incredibly useful.
    - Phemist 3y ago
      To put the focus on the principle of controlling your search engine results, rather than the specific tool (which is Kagi btw)
  - endemic 3y ago
    Can also use a DDG bang: https://duckduckgo.com/bangs?q=mdn https://duckduckgo.com/bangs?q=mdn
    - Phemist 3y ago
      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+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=requestAnimationFrame&ns0=1 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.
timvisee 3y ago
Then you haven't seen Rust's documentation yet. https://doc.rust-lang.org/std/index.html https://doc.rust-lang.org/std/index.html
- lytedev 3y ago
  I'm partial to Elixir's documentation myself: https://hexdocs.pm/ecto/Ecto.html https://hexdocs.pm/ecto/Ecto.html
- sjsanc 3y ago
  Compare MDN's entry for the `map` method https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe... With Rust's https://doc.rust-lang.org/std/iter/struct.Map.html 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.
  - timvisee 3y ago
    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.
    - lucideer 3y ago
      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).
    - recursive 3y ago
      Where's the noise? I'm not seeing any.
  - ndriscoll 3y ago
bob1029 3y ago
The quality of MDN gave me enough confidence to move away from frameworks and take matters into my own hands.
IshKebab 3y ago
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.

raincole 3y ago

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

bsmth 3y ago

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

dgb23 3y ago

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.

edlucas 3y ago
Kagi search also supports this bang shortcut, which I find very handy.
mintaka5 3y ago
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 =)

krono 3y ago

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/ https://html.spec.whatwg.org/ [1]: https://262.ecma-international.org/14.0/ https://262.ecma-international.org/14.0/

bazoom42 3y ago
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.
- bsmth 3y ago
  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.
- krono 3y ago
  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/ https://infra.spec.whatwg.org/ [1] https://webidl.spec.whatwg.org/ https://webidl.spec.whatwg.org/ [2] https://w3c.github.io/html-aam/ https://w3c.github.io/html-aam/ [4] https://w3c.github.io/html-aria/ https://w3c.github.io/html-aria/
recursive 3y ago
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.

thrdbndndn 3y ago

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 https://github.com/mdn/content). I've learned to always test myself when it comes to pesky/obscure behavior(s) of JS.

Xenoamorphous 3y ago

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

Phemist 3y ago
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.
- hju22_-3 3y ago
  Any reason not to mention which search engine you use?
  - leadingthenet 3y ago
    I'm not him but Kagi supports this functionality, and I make heavy use of it. Incredibly useful.
  - Phemist 3y ago
    To put the focus on the principle of controlling your search engine results, rather than the specific tool (which is Kagi btw)
- endemic 3y ago
  Can also use a DDG bang: https://duckduckgo.com/bangs?q=mdn https://duckduckgo.com/bangs?q=mdn
  - Phemist 3y ago
    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+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=requestAnimationFrame&ns0=1 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.

timvisee 3y ago

Then you haven't seen Rust's documentation yet. https://doc.rust-lang.org/std/index.html https://doc.rust-lang.org/std/index.html

lytedev 3y ago
I'm partial to Elixir's documentation myself: https://hexdocs.pm/ecto/Ecto.html https://hexdocs.pm/ecto/Ecto.html
sjsanc 3y ago
Compare MDN's entry for the `map` method https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe... With Rust's https://doc.rust-lang.org/std/iter/struct.Map.html 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.
- timvisee 3y ago
  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.
  - lucideer 3y ago
    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).
  - recursive 3y ago
    Where's the noise? I'm not seeing any.
- ndriscoll 3y ago

bob1029 3y ago

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

IshKebab 3y ago

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.