Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Documenting the Web together

blogs.windows.com

Post reply on HN
Print view View original

121–130 of 212 posts

Re: Documenting the Web together

#121

Post by bzbarsky »

edent wrote: post #77

We were speaking about this at the W3C's Advisory Board meeting in London earlier this week. It distresses me that the specs on w3.org are so hard to read for the average developer. It's great to see how MDN focuses on simplicity, readability, and usable examples.

There is a tradeoff between simplicity/readability and "define how to handle all the edge cases".

Web specs recently have sacrificed the former to handle the latter, not least because past experience with web specs that sacrificed the latter to do the former was so horrible...

Re: Documenting the Web together

#122

Post by pawelk »

schnevets wrote: post #95
Egidius wrote: post #14

For me, as an experienced front-end-focussed developer, MDN has been my go-to website for quick spec references. MDN has all I need to know, and I know my way around. However, I've been in teams where the less-experienced developers went to W3C Schools to see how they should implement some feature. And to be honest, I cannot completely blame them. W3C Schools shows directly what you need to know and how the API you a…

W3Schools tends to have a usable piece of example code at the very top of the page, while MDN gives an introduction and broader idea. Compare the display property page at the top of W3Schools vs MDN: W3Schools: https://www.w3schools.com/css/css_display_visibility.asp MDN: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d... Combine this and the higher Google rankings (My usual front-end searches display W3…

You should at least compare the docs for the same thing. For the w3schools article on CSS Display [1] the MDN counterpart would be https://developer.mozilla.org/en-US/docs/Web/CSS/display and to compare SVG docs on MDN vs w3schools I have a hard time finding an article with similar depth of information.

I agree there's a ranking problem, that's why I usually append "MDN" to my front-end related searches.

[1] The w3schools article on CSS display is limited to three values (block/inline/none) and doesn't even hint there are more possibilities, the most notable omissions being table and flex. It even has an example of overriding the default display ("channging inline to block and vice versa") that uses an `` which, by default, has `display: list-item`, and still doesn't mention it.

Re: Documenting the Web together

#123

Post by carussell »

bzbarsky wrote: post #121
edent wrote: post #77

We were speaking about this at the W3C's Advisory Board meeting in London earlier this week. It distresses me that the specs on w3.org are so hard to read for the average developer. It's great to see how MDN focuses on simplicity, readability, and usable examples.

There is a tradeoff between simplicity/readability and "define how to handle all the edge cases". Web specs recently have sacrificed the former to handle the latter, not least because past experience with web specs that sacrificed the latter to do the former was so horrible...

When this article first appeared, I wrote a long comment here (now deleted) about how the content Mozilla inherited from Netscape DevEdge originally straddled the split by fully embracing that there were two different mindsets the audience might be coming in with, and simply creating two different sets of docs. There were the JavaScript Guide and the JavaScript Reference, for example, and they were pretty thoroughly cross-linked.

It's been years since I stopped contributing to and reading MDN, but this editorial stance seems to have disappeared, unfortunately.

Re: Documenting the Web together

#124

Post by vivekkrish »

thanatropism wrote: post #115
vxNsr wrote: post #99

mdn.com is of course a 90s directory site for Muslims in Dearborn, Michigan. last updated by the looks of it in early 2016... maybe they'll relinquish the vanity domain?

What makes it a vanity domain? Just imagine how much printed material has circulated since the 90s with the mdn.com address. Why do you want to break the web?

For JS developers, there is already a short-hand URL, mdn.io.

It's quite neat in its functionality, allowing for searches via url params, like so: mdn.io/promise

Re: Documenting the Web together

#126

Post by tamonesto »

bzbarsky wrote: post #121
edent wrote: post #77

We were speaking about this at the W3C's Advisory Board meeting in London earlier this week. It distresses me that the specs on w3.org are so hard to read for the average developer. It's great to see how MDN focuses on simplicity, readability, and usable examples.

There is a tradeoff between simplicity/readability and "define how to handle all the edge cases". Web specs recently have sacrificed the former to handle the latter, not least because past experience with web specs that sacrificed the latter to do the former was so horrible...

x

Re: Documenting the Web together

#127

Post by vbezhenar »

edent wrote: post #77

We were speaking about this at the W3C's Advisory Board meeting in London earlier this week. It distresses me that the specs on w3.org are so hard to read for the average developer. It's great to see how MDN focuses on simplicity, readability, and usable examples.

Specs are not meant to be read by average developer. Average developer should read books. Specs are meant to clarify moot points between different implementations. Spec is like legal document, they are hard to read, but they serve their purpose.

Re: Documenting the Web together

#128

Post by jessaustin »

Zpalmtree wrote: post #117
kbumsik wrote: post #7

The is great indeed. I hope w3schools.com won't appear in Google search result. BTW, It feels like OP omitted to mention to MS in the title though.

I barely webdev, but when I do, I've found w3schools pretty helpful. What's wrong with it?

Most people that have used both w3s and Mozilla Dev Network prefer MDN, and formerly were disappointed that w3s's better SEO formerly meant wading through their links when googling.

Re: Documenting the Web together

#129

Post by mshenfield »

fyrstenberg wrote: post #30

Don't forget you can use https://devdocs.io/ too which also searches MDN and store offline. The two are a great pair.

Was on a plane ride this weekend and was thinking how I needed to re-install Dash so I could have an offline docs viewer. Personally like the web format much better, thanks!
Post reply on HN