4 ms·

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

by 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.
chrismorgan 3y ago
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!

by krono 3y ago

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.

chrismorgan 3y ago

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!