Documenting the Web together | Hacker News Reader

Documenting the Web together

blogs.windows.com

1,210 pointsmarvinpinto203 comments

I really miss the old MSDN Library. The 5GB installable one you'd get as one of the 200 DVDs in that giant case they'd ship you with your MSDN subscription back in the day.

It was awesome. You could hit F1 and it would instantly pop up good, detailed, documentation for whatever method or keyword was under your cursor. In any of their developer products, so it worked as well in SQL Server Management Studio as in VS.NET. Every language, every technology, updated monthly via Automatic Updates on your dev box.

But they stopped shipping it in favor of "web help". That's the thing where you hit F1 and it spends several seconds opening a web browser (a custom one in a new tab in the IDE for some reason), then several more seconds opening a "meet the mouse" style page telling you how to use the code editor window (which it had helpfully detected was your context when asking for help).

So in one stroke, they switched from the worlds most awesome help system at your fingertips to "just go open Chrome and type your search into Google, since that will at least get you something relevant".

Today, they've improved that workflow by trying to ensure that something relevant exists on MDN, provided you're searching for web-related stuff.

We're still about 10 years back from the state-of-the-art in 2003.

Shame.

Yeah, the old installable MSDN Library was really great. I loved how they approached each topic with three types of documentation: tutorials, concept overviews, and types-and-functions references. I still have the CDs on my bookshelf because I can't bring myself to throw them away. :)

Microsoft was really good at developer documentation.

Apps like Dash and websites like devdocs.io come close to the same experience, at least.

VS2017 opens the correct documentation most of the time, and in the default web browser.

For C++, cppreference provides archives of all their docs: http://en.cppreference.com/w/Cppreference:Archives.

Of course, that won't help you for Win32 or .NET.

There's also https://zealdocs.org/

There's also https://github.com/jeaye/stdman which provides the pages from cppreference as manpages, and https://github.com/aitjcize/cppman (which I haven't used, but seems to look a bit nicer)

Visual studio is not the only tool that went online. Many MS office products went this route. AutoCAD did too. However, AC has an option to download offline help. The office products have an option to stay offline. It does not work that well, in my experience.

I guess some guy at MS thought: People look online for solutions; We should do that too!

They broke things because the web browser was slow and the search results sucked.

There is potential for improvement. The platform is set for that. But only if someone could go and do the work we would not be talking about this anymore.

The help function in Excel has been so useless and disruptive to work over more than a decade that I know many people (Excel power users) who just removed the F1 key. It got slightly better with Office 2016 but is nowhere nearly as productive as just googling your problem.

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

There is also mdn.io which can be used as shortcut in every browser like this (for a search for 'await'): http://mdn.io/await

It seems neat on the surface but it also seem to involve two redirects, first one to google.com (which is not obvious and personally not something I would like), and then to MDN. It would be cool if it linked directly to the page on MDN or showed the content directly within the page.

And the second time I clicked I was met with this message, not mdn.io's fault but nonetheless (i.e. "google police" - not sure what they mean with "unusual activity", there is hardly any at the moment - maybe not enough? :) or maybe I just got a busy vpn exit point): https://imgur.com/itn48dZ

Yup, that site seems to be basically redirector to Google redirector [1].

You can get the very same effect like DuckDuckGo keyword search but with "just the last redirect" with vanilla browser bookmark [2] with `%s` interpolation:

    https://www.google.com/search?btnI&q=%s%20site%3Adeveloper.mozilla.org

[1] https://github.com/lazd/mdn.io [2] https://www-archive.mozilla.org/docs/end-user/keywords.html - old page about feature in Firefox (currently the same works in Google Chrome as well). Amusing that the this `btnI` search is in the second example there.

If you set up your browser's default search engine as DuckDuckGo, this works from the location bar (at least in Firefox):

    !mdn await

This will perform a query to DuckDuckGo (the non-tracking search engine) first, and automatically redirect to MDN.

No need for extra add-ons; this is one of the standard set of 'bangs' DuckDuckGo provides.

If you go to chrome settings -> Manage search engines and define a new search engine with Keyword: "m" and "URL with %s in place of query": https://www.google.com/search?&q=site%3Adeveloper.mozilla.or... typing "m await" in the omnibar will jump to the first google result from MDN, which is what it seems mdn.io does.

https://news.ycombinator.com/item?id=15306429 is my list of custom search engines.

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!

cool, i didn't know that site. wonderful ux

how's the content added though? its missing so many libraries i use...

They have a Trello board where you can suggest and vote on additions. https://trello.com/b/6BmTulfx/devdocs-documentation

Seems to be scraping public documentation pages

https://github.com/Thibaut/devdocs/#scraper

Here's an alternative if you would prefer a desktop app

https://zealdocs.org/

While we're on MDN related awesomeness, shameless plug: Back when I was in school, I made this Chrome extension which allows you to jump directly from the address bar to the MDN page you want:

https://chrome.google.com/webstore/detail/mdnjump/mfjekjhknp...

If you use DuckDuckGo as your standard search engine you can also prepend "!mdn" to your search query to search MDN.

This also works with any website wich supports search I think. Other good ones include "!hoogle", "!hn", "!yt", "!g", and the list goes on.

FYI, if you're already shortening the so-called "bangs", you could use "!h" for Haskell. :)

Worth pointing out: submitting bang ideas is very, very trivial, but the whole process may last months. Last time I've read about someone complaining about a long bang, I've submitted "!gw" as a shorter version of searching Gentoo's Wiki and it became a thing a couple of days ago. This is maybe fifth or sixth bang that I've submitted to them via https://duckduckgo.com/newbang.

This will bring you to a search result page, yes? My ext combines Google's I'm Feeling Lucky to jump straight to the page for the top result, which I find works 99% of the time I'm looking for something on MDN.

I'm using it as my primary source of documentation since a couple of years. Never been disappointed, and it saves a lot of clicks.

Yeah wow thanks! This is great

Thanks for sharing, this is awesome

No Elm there?

230+ sets of documentation already work. You can vote for your favorite language here: https://trello.com/b/6BmTulfx/devdocs-documentation

thanks for this one!

Guess they are going to band together to dethrone W3Schools :-) (only half kidding, that web site has has some serious staying power.)

Related, when I was active in standards work (I learned just how badly that stuff was run) I discovered that new people in a standards group that was being formed would be lobbying to be the group Chairperson or Vice Chair. But the people who had been in standards bodies before were all vying to be the Editor. That was because the group could argue all they wanted but at the end of the day what was in the standard was what was in the document and only one person had absolute sway over that, the Editor.

So when I see all these leading lights, who just got through a rancorous debate about DRM with the standards body, endorse a new way to capture the "actual" standard, I see a seasoned standards wonk offering to do all the slavish work of editing the documents so that everyone else can focus on the hard work of coming up with the best possible standard.

W3School is very good to quickly look something up - short and always with a simple example.

MDN is very good for details and in general as reference.

Short and always with a terrible example. I would never trust W3Schools with the simplest stuff. Take this form documentation, they don't even mention using <label>

https://www.w3schools.com/html/html_forms.asp

Sadly, "html forms" brings up 3+ W3Schools pages of at the top.

W3schools is contributing to poor education amongst junior web developers.

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.

I think that’s a very narrow view and it’s far from universally true. While a lot of W3C specs are impenetrable there are many counter examples at the IETF which might not be introductory level but are certainly easier for a developer familiar with the topic to follow.

I think this is actually fairly important for two reasons. The first is simply that unreadable specs are just as bug prone as unreadable code, but the second is that this increases the distance between the web as specced and the [much much much] larger developer community, and things like <img srcset> / <picture> show the benefit of having less of a communications chasm between those groups.

That doesn’t mean that specs can’t be precise but simply that good technical writing can accommodate a wide audience.

I think it also largely depends on what the spec describes. XML for example is rather abstract and can be hard to follow, but SVG is quite easy to read and in my opinion much better than any 3rd-party explanation (primarily because it's complete and error-free).

These specs are still designing systems that will be used by humans. If they can't be communicated effectively by the designers then it's likely they are too complicated themselves.

It would be a good exercise to require the public documentation parsable by humans. At least when it gets beyond the proposal stage.

The thing is it shouldn't be that way in the first place isn't it? Take the golang spec, for example.

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.

Python's official docs do a good job with this approach too, I think. The Python Language Reference is relatively easy to read for a lay-man when that's necessary, and includes the formal logic of the spec in little call-out boxes -- but it's also accompanied by the Python Tutorial, which manages to cover nearly everything while making no attempt to get into every edge-case and obscure method, keeping it focused and readable. It's a great learning tool to get up to near-proficiency, and then the Reference is there for all those little "but I wonder what happens when..." questions.

Oh wow, I disagree with this quite strongly. I find they lack useful examples, and it's ridiculously hard to find even the list of methods.

What even does "the list of methods" mean? Do you mean the builtins? Those are at the docs for built in functions.[1] Or do you mean the list of all functions? Because that doesn't exist for the very good reason that it doesn't make sense to have a list like that for python. There's the module index[2] though which lists every available module, linking to their docs which list all the available functions in those modules.

Having a single list of all functions in python makes very little sense for the simple reason that you'd not be able to find what you're looking for in that list so you might as well just use the search in the first place.

Side note: if there's a specific function you'd like to get the documentation for you can get that easily from the interactive python prompt with the "help" function:

    >>> help(zip)

And I fail to see the "missing examples". While it's true that most modules don't contain examples for every single function they usually contain a few examples for the overarching concept.

So which part exactly of the python docs is bad? IMO they are, by far, the best docs any programming language has.

[1] https://docs.python.org/3/library/functions.html [2] https://docs.python.org/3/py-modindex.html

Yes, I realize I can use help. Does it being available in one place mean that it shouldn't be available in others? If I'm in an IDE I don't always have the command prompt in front of me, and that should be fine!

So here's the standard library page for Python lists: https://docs.python.org/3/library/stdtypes.html#sequence-typ...

As a new python programmer, how am I supposed to know that the comprehensive API docs are actually in the tutorial? https://docs.python.org/3.1/tutorial/datastructures.html

Compare that to Javadocs (something Java got right!): https://docs.oracle.com/javase/8/docs/api/java/util/List.htm..., and .NET is similar. Ruby is also ok in this regard: https://ruby-doc.org/core-2.2.0/Array.html

(Javascript is a mess of course!)

I think Python is the worst-documented large language I use.

For ```list``` it says:

Lists implement all of the common and mutable sequence operations. Lists also provide the following additional method:

...where "common" and "mutable" are links.

Meaning: the methods of lists are strewn across three different location, four if you count the constructors above this sentence.

Some context: the page documenting lists [0] is the same page that documents all* Python's built-in types; lists are documented in section 4.6.4, where section 4.6 is titled "Sequence Types — list, tuple, range".

Many operations on a list are much the same as the methods on a tuple, so they are documented in one place – section 4.6.1 "Common Sequence Operations" – rather than duplicated in both the list and tuple documentation. Similarly, many of the methods supported by list are also supported by bytearray, so they are documented in 4.6.3 "Mutable Sequence Types" rather than duplicated. To get from the section on lists to the two sections describing the available methods involves pressing page-up twice. Hardly "strewn across three different location", and there's always help(list) if you really want a list of every supported method.

*all the ones you'll use regularly, at least

[0]: https://docs.python.org/3/library/stdtypes.html#lists

As a "lowly CSS developer", I'm actually okay with this. w3.org specs are meant for browser developers, MDN docs (supposedly) are meant for web developers.

MDN resources are written for web developers (ie. consumers of the already implemented language spec). The W3 spec has to be written for its implementors and is necessarily much more complicated.

Mozilla Blog post: https://blog.mozilla.org/blog/2017/10/18/mozilla-brings-micr...

Google blog post: https://blog.chromium.org/2017/10/building-unified-documenta...

Interesting that there is no Apple representation.

Apple never hosted web-related docs, so they probably don’t care.

Sorry, that is not true. Apple documents all of its platforms quite thoroughly, and Safari is one of them. Theirs is simply not an analogue to MDN.

https://developer.apple.com/library/content/documentation/Ap...

“Apple doesn’t attempt to document general-purpose Web technologies without an eye on its own platforms” might be a more accurate statement, but even that is shaky because they spent a lot of time explaining HTML5 media while killing Flash.

Ah. Missed that. Yup. It would be nice to see Apple's support behind MDN as well.

Representation? You've got an app for that ;-)

So, can maybe Google finally push the w3schools out of their SERP? :)

This is a great start. Now let's integrate caniuse into every single MDN page.

MDN already has compatibility tables for lots of things; if they're missing from a particular article, it's not because they're unsupported, it's because nobody has done the research and filled in the information (it's a wiki! You can add things!).

No need to duplicate the effort though, caniuse usually links to MDN for feature reference anyway.

If caniuse had embeds, they could easily replace the existing compat tables on MDN.

MDN didn't do a good job of advertising itself as a wiki. It wasn't until recently that you could login with a GitHub account.

When you google "can i use flexbox", caniuse.com comes up but MDN does not.

The other thing missing from MDN, is that caniuse.com shows browser support as a percentage. Now I know I'm safe to use flexbox since its supported by 97.74% of browsers in the wild.

When a new feature comes out, I add it to both MDN and caniuse. It would be great if these two could be integrated as well.

I don't like that caniuse by default shows only several recent browser versions, deceiving developers and making it look like some new technology is supported everywhere. It is clearly a "dark" UI pattern that motivates developers to make sites viewable only on latest Macbook.

Instead, it should show the year since which some feature is supported.

For example, for flexbox it could write:

IE - never

Edge - since 2015

Firefox - since Mar 2014

Safari - since Oct 2013

Opera - since Nov 2012

etc.

This gives a better picture.

I actually like how it currently works because it doesn’t matter if Chrome 32 didn’t support feature X because no one is using it. The boxes are sized by their current usage and aligned based on the stable version.

It’s a perfect chart to show your boss when someone complains about Firefox 4 not working. Clearly that person missed a few updates :)

That being said, I would like a year on each column for the occurrences when time/year is relevant. Currently I just Show All.

It the meantime, this sounds like a good idea for a browser plugin.

Déjà vu. Previously (checks email …almost exactly 5 years ago?! Christ, it was a long time ago), the web powers that be announced they were going to collaborate on a new web docs wiki.[0] I don't think it went anywhere because, well, MDN already existed.

I'm glad they finally just surrendered to MDN, even if it was many years late.

[0] https://www.w3.org/2012/10/webplatform.html.en

They chose a different license that made it more difficult than it should have been to integrate content from MDN. The two sites' backends were completely different, too, so the source texts needed to be tweaked before publishing. I also remember that for for many of the docs, they favored basing them off MS's contribution (IIRC). It also had a very un-wiki-like atmosphere, where the lifecycle of a change resembled a code review, i.e., the opposite of the "be bold" policy that led to the success of Wikipedia (and the early days of developer.mozilla.org).

Was the WebPlatform project?

> The WebPlatform project, supported by various stewards between 2012 and 2015, has been discontinued. This site is now available on github

https://webplatform.github.io/docs/

"One of our guiding principles in developing Microsoft Edge is that end users should never have to worry about which sites work in which browsers. This philosophy—”the Web should just work for everyone“—led to our choice to target the “interoperable intersection” of web APIs in our browser engineering."

Many sites already don't work correctly in Edge, IE11 nor Firefox - it's too late, these are minor browsers, used by a smaller fraction of end users. End users on on smartphones use 95% a WebKit originated based browser aka Chrome/Safari. Chrome and Safari are bigger than the rest on desktop.

Sites in 2017 are tested against Chrome and Safari by web developers.

http://gs.statcounter.com/browser-market-share/desktop/world...

http://gs.statcounter.com/browser-market-share/mobile/worldw...

Minor is very relative here, especially with regards to Firefox. IMO anyone who only tests against Chrome and Safari is seriously wrong. The amount of features not supported by Firefox or Edge are relatively small and so basically everything except for a few special cases should just work everywhere.

Chrome descends from WebKit, but it isn't WebKit. As I unfortunately learned recently when a workaround for a WebKit bug broke modern Chrome.

It depends on the user base. Customers of the company I work for mostly use IE or Edge and only Chrome because we highly suggest it. Without decent IE/Edge support we would have less customers.

lol sure,

from analytics

chrome 38.17%

safari 20.30%

firefox 17.10%

ie 15.56%

edge 7.08%

A few years ago most of these companies got together to do the same thing and launch the WebPlatform for the same thing. If you watch the video, you can see some guy named Tim Berners-Lee with a title "Web Developer" say it was the place to learn.

I wonder why they are relaunching instead of using Webplatform.Org ?

Can't beat them, join them. Developers simply go to MDN and MDN often is on top of the search results anyway. It often gets linked from stackoverflow too.

I think MDN is already quite a trusted reference for developers, so abandoning that would be abandoning a lot of “brand value” that’s been earnt through lots of hard work.

Federated content is hard.

Totally OT, but "Today, we’re excited to " is as an opening statement, through its ubiquity and seeming robotic mindlessness, is starting to distract from the actual topics. Maybe just me. Still. Just sayin.

What else can you even write instead though

In this case, there could be literally nothing instead.

> (Today, we’re excited to share some big news for developers around the world wide web: )We’re committing our resources towards making MDN Web Docs the best place to go for web API reference.

There needs to be an intro or it sounds very weird.

Agreed. Keep the word "Today".

Microsoft you are doing all the right thing to win the hearts of developers! Great! Thanks for all wise decisions

This news sounds great to me, but I feel like I don't understand what's happening behind the curtain and don't grasp the second-order consequences. What would motivate them? I wonder what the political motives are (industry politics, not the other kind that we won't mention here).

Could this eventually displace standards bodies such as WHATWG and W3C? If the Product Advisory Board of Mozilla, Google, and Samsung agree on a standard and publish it at MDN, will that become as official, at least de facto, as a standard published by W3C? I do see W3C is mentioned as a participant.

Also, for the sake of argument (and IMHO, of realism) let's assume that Google, who can virtually set web standards themselves these days, isn't doing this for a purely altruistic motive of supporting the open web. Why would they give up the 'soft power' of writing their own documentation for their own standards?

Complements and substitutes: https://www.joelonsoftware.com/2002/06/12/strategy-letter-v/

Modern web companies don't make money from the web, they make money from something you do while you're on the web. The less the web costs to use (in the broadest possible sense of cost), the more people will use it, the more money they will make.

That's why Facebook's trying to pay off Indian ISPs, and Google's pouring money into web browsers and internet balloons. Microsoft came late to this party because their original make-money-from-the-OS model meant they were trying to compete using the browser, but now that they have a cloud strategy like everyone else, the law of complements has turned them into good web citizens too. Thanks, Satya!

I think there are several motives:

1. The people working on these browsers are just that: people. They haven't necessarily been e.g. at Microsoft when IE vs. Netscape was a thing, and probably don't hold grudges. They were hired to work with the web, not against it.

2. There was a lot of duplicate efforts, and MDN was clearly "winning". That's a waste of time.

3. A more "neutral" MDN (although I think they've been doing a pretty good job already) is good for all browser makers. Even if Mozilla and its volunteers are trying to be a non-biased resource, they'll always be writing from their own viewpoint.

4. For Mozilla, MDN being less Mozilla-/Firefox-focused might not sound like a great option, but Mozilla's mission is to build a better, free and open internet, not to be dominant. (Incidentally, that's also the reason MDN "won": this made it able to attract many contributors and supporters.)

In general I like that Google and others are doing this. The web is so complicated, so overwhelming, that a central source of documentation is needed. This "blog posts as documentation" culture is not healthy.

However I think we should all be skeptical of any actions corporations take today until proven otherwise. When 60,000 Americans are dying of opiods per year (that's all the deaths in Vietnam per year) and drug companies will reject calls to regulate them and pay off members of Congress, some constant skepticism is called for (who could of believed they would do that??) https://www.washingtonpost.com/graphics/2017/investigations/...

> (who could of believed they would do that??)

I didn't even realize I was being cynical when I was unsurprised by this news. I don't really understand why everyone else is. (That isn't to say it isn't important news, but the shock that everyone seems to be in is confusing).

Supporting open web is not altruism. Proprietary standards on web is pure evil even for companies: see what happened to IE or Flash.

My favorite line was this:

One of our guiding principles in developing Microsoft Edge is that end users should never have to worry about which sites work in which browsers. This philosophy—”the Web should just work for everyone“—led to our choice to target the “interoperable intersection” of web APIs in our browser engineering.

It wasn't favorite because I agree with it. It was favorite for the humor value of Microsoft accepting a principle that flies so strongly in the face of how the company established itself, managed its battles with competitors, and tried to sabotage existing web standards for most of my professional life.

I'm glad they are finally claiming to be on board. I'll trust them as far as I can throw them. (Guess how far I can throw 120k people...)

People change, and so do its companies (or at least, their management).

Looking from a non-Windows-user perspective, in the last couple of years: VSCode is now a thing, .NET is open sourced, they've started financially supporting organization that I like (like OSI and the Linux foundation), Powershell is now available on my platform, and, if I ever decide to switch back to Microsoft's technologies (highly unlikely), I have Windows Subsystem for Linux and I'll be able to run Linux servers on Azure.

As a non-Windows user, I'm totally happy with this new Microsoft.

MDN is an AMAZING resource, and I'm glad that it's getting the attention it deserves (both from Mozilla and the rest of the internet). Really hope this effort lasts over time as the effort put into MDN by volunteers, besides Mozilla employees, is tremendous!

Hope MDN becomes the go-to Wiki for the web (It practically is for me already)

Kudos to the team! :)

Awesome! Great to see that Mozilla gets the approval, respect and support from such big players.

Looks like there is hope for a free and open Web! Well done Mozilla!

> One of our guiding principles in developing Microsoft Edge is that end users should never have to worry about which sites work in which browsers. This philosophy—”the Web should just work for everyone“—led to our choice to target the “interoperable intersection” of web APIs in our browser engineering.

That's a good move by MS. In this context it's great to see them supporting open codecs, and for istance OGG container for audio which was recently announced as work in progress in Edge. Quite a turnaround from the old times of "best viewed with IE", ActiveX, Silverlight and etc.

Why can't MS apply same principle across all their teams? Compare the above to their push for 3D graphics API lock-in.

Also Edge is the only web browser where Netflix can be streamed at 1080p and 4K. OTOH Chrome and Firefox are only at 720p. Safari is at 1080p though. (Netflix's windows app is another route)

Edge also supports Apple's Live streaming tech so, again the only browser on Windows which can be used to watch Apple's Live events.

Too bad that Edge won't ever be on Linux.

> where Netflix can be streamed

Isn't that because of Netflix's choices, rather than technical reasons?

I'm not entirely sure. I believe it has to do with the DRM implementation. While Widewine is the DRM in Chrome and Firefox, Edge uses something different[1].

I've seen people talk about Chrome being able to handle 1080p in ChromeOS. So there seems to be more than just Netflix's choice involved here. Although I bet Microsoft being proactive helped. Definitely unclear.

Also I don't see any reason why Netflix wouldn't want to support 1080p in all the major browsers. The only downside might be excess bandwidth, but with the Open Connect Appliance being a thing, I doubt it is a big factor.

[1]: https://blogs.windows.com/windowsexperience/2016/07/13/get-b...

As far as I understand it, you need tight coupling between the browser and the OS to implement the sort of deep-reaching DRM that Netflix/Hollywood wants for 1080p. That would explain why Edge on Windows and Chrome on ChromeOS can do it.

Personally, I see it as a plus that my browser/OS combo does not support this. There have to be horrid security implications that just wait to be unturned.

Indeed: https://www.schneier.com/blog/archives/2007/02/drm_in_window...

Insistence on DRM ironically is causing the opposite effect - wider piracy of DRM-free versions.

If it's because of DRM, it's the fault of Netflix. No one stops them releasing their video DRM-free.

It's not the first time DRM hampers performance and thus degrades usability. It's by definition an anti-feature.

Well, they ported their Javascript engine to *nix[2]. Also, it's not like Internet Explorer wasn't supported in Unix 'back in the day'[1]...

[1] https://en.wikipedia.org/wiki/Internet_Explorer_for_UNIX

[2] https://github.com/Microsoft/ChakraCore

Yet here I am and still have to fight flexbox bugs in IE 11 they were too lazy to fix for 2 years and then closed the ticket because IE 11 was legacy at that point.

MS only implements standards when they don't get to make one. They didn't want to implement WebGL in their browsers until Safari/Chrome/Firefox had it and they risked being behind.

Same thing here. "Web should just work for everyone" means "Oops, people are making Chrome-only websites, we need to catch up on web standards so we aren't left out". Meanwhile they'll boast how you need Edge to watch 4k Netflix.

Because video-games is still the one place where Mac and Linux are lagging behind, and they have DirectX to thank a lot for that.

In case of Linux, you forgot availability of drivers, cohesive user experience, stability and ergonomy rather than programmer designed interfaces.

I guess I should have said "Mac or Linux", but I'll answer your points because they tick me off.

First some context : I'm both a Windows, Mac and Linux user, and my favorite is probably Mac. But I've converted a fair share of my family to Linux (my grandma too) because it's more predictable than Windows, and cheaper than MacOS (I'm basically my family's IT hotline). Most of what I'll talk here is a mix of my own experience, and feedback from my family members.

Let's talk about drivers. Turns out, drivers are available for most of the hardware you'll need (which is basically GPU, WiFi, Bluetooth and Webcam). Sure, this weird piece of equipment might not have linux drivers, but in truth I can't even remember the last time I've hit that problem. I don't think equipment compatibility is the reason people use Windows in 2017 anyway, given we're all using Android/Linux on our smartphones and tablets, so I'll move on.

Let's talk about cohesive UX. Windows, since 8 and 10, has the least cohesive UX ever. Running Gnome or KDE on Linux today will get you a more cohesive UX than win10, and that's no compliment. Half the Windows apps still use the old winforms look, half use the new metro (or whatever it is called) look, and then there's all the webapps that have their own custom look and feel. Cortana is a clusterfuck of an UX, the File Manager has this weird "It's a filesystem but not really" mentality (the location bar doesn't show the full hierarchy, WHY ?), and there are so many papercuts here and there that I end up fighting my OS half the time.

Let's talk about stability. Windows forces reboots every few days because it has "mandatory updates". Windows basically built this feature where they force the computer to reboot and the user has absolutely no say in the matter. This is not the stability guarantee I'm looking for. Another anecdata : one of the few family members to still have a windows has a Microsoft Surface Pro. She has to reboot it every few days because it won't detect the Wifi card anymore. Microsoft can't even make their own OS stable on their own hardware.

Windows might have been good at all of this at one point, but that's not the case anymore. It's become terrible at all of it. So bad that Linux slowly creeped its way into my family, and that made my life much easier.

Windows is better and more efficient than it ever was, thanks to many improvements since Windows 8.

https://np.reddit.com/r/Windows10/comments/74xc2z/windows_an...

Most default Windows apps are UWP with Fluent Design now, and more are migrating towards that since they have major advantages that you won't find on Mac and most Linux distros

https://np.reddit.com/r/Windows10/comments/75lgti/announcing...

Also, your other points mostly contain misinformation.

I never claimed windows hasn't been getting better in other departments. And I'll agree that a default Windows install is probably more battery efficient than a default Linux install. But that wasn't the point.

To respond to your point specifically, I said the UX in windows 8/10 is terrible. I hope it gets better, but right now, strictly speaking, win7 was the last time windows had a cohesive UX.

And please tell where the misinformation is. Mandatory updates were a thing[0] (seems they fixed that, good). The wifi card problem on surface pros is documented[1]. The explorer does break the hierarchy analogy consistently, you can see by yourself that the location bar doesn't show the full hierarchy when you access "Libraries" (whatever those are).

When you claim misinformation, please say what is. It might allow me, or you, or someone else in this thread, to learn something !

[0]: https://www.cnet.com/news/microsoft-windows-10-forced-update...

[1]: https://www.windowscentral.com/microsoft-acknowledges-surfac...

So, MS isn't new, it's same old MS, and their good behavior happens only when they already lost their monopolistic grip. Q.E.D.?

Privatize the profits, socialise the losses. This is why commercial companies cannot be trusted to sustain a wiki, open source, or free software model.

Nonsense, any of such APIs are abstracted away in most game engines, and cover only a tiny fraction of a game engine codebase.

You sound like engine developers just produce those abstractions out of thin air and they work perfectly out of the box. They need to work on them and waste their time on duplicating efforts. Bugs that plague Unreal Engine for instance demonstrate how far from trivial this is.

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.

Sorry, I don't understand the overriding sentiment here..

Are we now asking Google et al to be the gatekeepers of what is deemed correct and useful because they have a preferred alternative that fits with our view on the world?

W3Schools may not have the best historic reputation, but it still has a place in relevant search results.

I have personally used MDN extensively over the years, and love it for what it is.

Google already overrides ranking to put its own preferred things first in your results. The time to complain about Google being a "gatekeeper of what is deemed correct and useful" was years ago; now it's far too late.

Duckduckgo is the way to go. Priorities MDN and Stack Overflow, really good search engine.

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

Historically, w3schools had a lot of outdated (or outright wrong content):

http://www.w3fools.com/

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.

This is great news. I learnt JavaScript from MDN first and it was a great resource. Still use it almost everyday as a reference, would love to see it grow.

I can only hope MDN does to w3schools what Stack Overflow did to experts-exchange.

What would be the best way to download MDN for offline use? A quick search shows: https://developer.mozilla.org/media/developer.mozilla.org.ta... https://kapeli.com/mdn_offline https://zealdocs.org/ Any experience with the above?

Definitely https://devdocs.io

If you are on macOS, then Dash (by Kapeli) with the CSS/HTML/JavaScript docsets is your best bet. Having offline docs available at the speed of my fingertips throughout your OS has been a fantastic productivity booster for me. I'm not a heavy MDN user, so I don't know if there's anything that's not covered by the above three docsets.

If you are on Windows or Linux, then Zeal and Velocity are basically the same thing (they're only available on platforms where Dash isn't). Zeal's search used to be pretty bad, but at least you have the option to send Pull Requests on GitHub.

Hopefully that will push the ranking up for MDN articles.

I wonder how much influence over MDN content these new contributors will have. On the one hand, it looks like a victory for Mozilla and developers everywhere; on the other hand, it looks like this will amplify Google's voice on the direction of web standards and help grow Chrome's market share at the cost of Firefox's.

I'm so happy to see this! MDN has always been my go-to resource for any JS/CSS help

Already was the place to go.

Somehow I had more luck with stackoverflow and others when looking for a quick hint/example.

Yes, for hints like "how do I", but for JS ref like "methods on a Set" I use it all the time. Problem with SO is that often the anwsers are quite old (<=ES5).

Why Samsung?

Probably a case of having engulfed the industry so much that just throwing money into the industry will actually pay out for them in the long run.

And it's probably also just nice to be able to bite Google and Microsoft in the butt here. Those do benefit from a healthy web and both very much need the PR of supporting webstandards, but they could also both benefit a lot more from controlling a platform like MDN and then sneaking in pseudo standards here and there. So, Samsung helping out with MDN makes it even harder for one of those to build up their own version.

Lastly, Samsung does ship their Samsung Internet Browser on all of their Galaxy devices, which has got to be a somewhat significant share of daily internet users. Currently, that's Chromium-based, but they could be looking to eventually follow Google and Microsoft in making up webstandards.

They've also already invested into Mozilla's Servo, so maybe they're also just trying to build up a partnership with Mozilla to help to take on those giants.

From what I've heard, Samsung Internet Browser is trying to lead the way with WebVR (Virtual Reality).

https://webvr.rocks/samsung_internet

Together, except for Apple that does not care.

Are they still pushing Edge?

> redirecting

Cool!

This is great news, but the title misses out on the fact that Microsoft (the blog poster, nonetheless) is part of the "others" joining. Revising for clarity would be good.

Yeah. And the link is actually to a blog post from Microsoft stating they started redirecting MSDN pages to corresponding MDN ones.

Given that the blog is on windows.com and it mentions MSDN, I think the title should include Microsoft as well. I was actually confused/befuddled seeing the juxtaposition of Google and Mozilla in the title, and windows.com as the domain in brackets to the right of the title.

We've reverted the title to the article's original which, since it is neither misleading nor baity, is what the guidelines call for (https://news.ycombinator.com/newsguidelines.html).

The submitted title was "Mozilla, Google, others team up to make MDN Docs the place to go for web API ref" which is actually an uptick in misleadingness, as you and others pointed out. Submitters: please don't do that.

Great, while they are at it can Google please downgrade the extremely spammy w3schools or at least allow me to remove certain websites from my searches. There are so many better resources out there...

I've never understood the hate for w3schools. I've always found them to be extremely useful. I like that usage examples is the focus of their site. I find that more useful than wordy documentations that more advanced references provide.

http://www.w3fools.com/ top of the page summarizes the situation:

> 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.

MDN would greatly benefit from more soft documentation and a playground setup similar to W3Schools

I'm still waiting for the true spiritual revival of HTML Goodies https://web.archive.org/web/19980130110903/http://htmlgoodie...

Or not. MDN usually suits me fine.

Actually, I find TutorialsPoint https://www.tutorialspoint.com/ generally pretty good, if not lacking in some depth. They give a decent soft intro, though.

I think if you tried to add that to mdn you’d make it worse at what it’s good for

When I was a noob, w3schools was far more useful. I learned HTML and CSS on w3schools. Now I'm more of an expert, I need the detailed documentation that MDN has. Each site has its niche. Still sometimes reference w3schools because it's easier to read, though.

Yeah, MDN is akin to Unix man pages, W3Schools is more to the point.

They've corrected most of the bad sample code.

They aggressively create separate pages for every element and attribute, each full of ads, but hardly any containing substantive descriptions of the things they document. At worst they just restate the name of the attribute in different words. And the examples, while sometimes nice, often just show the effect of turning a property on or off and don't really demonstrate the different things you can do with it. If they focused more on substance and less on SEO, they could be a much better resource.

I'm surprised. This is the type of thing that should fall within the Panda update cross hairs. Thin content, heavy ads - Google should by design be favouring pages that aren't shooting for cheap long tail hits.

At this point (trying to be a good citizen, not using an ad blocker) the ads on the site lock up my computer, and a simple lookup turns into a substantial time investment. Vs MDN doesn't have this issue.

How can you use the web without an ad blocker? Anytime I get on a browser without an ad blocker I'm reminded of how slow and horrible the web used to be (and apparently still is).

They were great in 2006 when I was learning, but they're not nearly as useful as MDN (even foregoing the accusations that w3schools is errant and spammy). It's simply annoying to have to manually filter the w3schools (and others) search results when MDN is sooo much better.

I use w3schools and MDN, both. w3schools improved a lot over the years, and it's easy to find something fast. MDN is more in depth. CanIuse.com is another very useful resource. Google should keep all three resources in the top results.

Wc3 is good as a reference to html or css syntax but I feel it's spread it's tentacles to far and wide. It's the first result when I search for a php method, and I don't feel it's nearly as good as the php manual

I’ll never/rarely click a w3schools link, but I do find MDN to be quite difficult to read with it’s pages being quite technical and terse. W3schools is quite pragmatic with providing a reference for CSS properties.

I hope these extra resources will let MDN improve on this.

Yeah. I treat w3schools vs MDN like Simple English Wiki vs regular Wikipedia. There's some subjects on Wikipedia (like math particularly) where to understand the wiki page, you need such a good background that you don't need the wiki page anyway. It's good to have a simpler, not complete place to get your feet wet first.

Exactly. Sometimes I just close MDN and then click on w3schools link for this reason.

I agree. I feel like going to MDN to quickly look up syntax is like trying to kill a fly with a handgun.

I’m quite the opposite, I feel like MDN is the only sane resource in an ocean of opinionated crap. Not saying it covers everything but for syntax it’s practically the only place I visit.

Same here. For syntax and quick examples, I find w3schools much harder to parse than MDN. Maybe there's more noise in w3schools, or maybe the layout/design of MDN are better for these purposes.

But going to w3schools is like trying to kill a fly with a flyswatter with a dashed red border of weight 2px. Their examples are so basic, pre-canned, and repetitious between pages that you rarely see useful options and intricacies that each tag/property may posses.

For super quick syntax checks ("Is it fill-opacity or opacity?") MDN might be a little overboard, but as any sort of reference beyond 3 line snippets it is the link that I always look for. I usually append MDN to the end of my searches for HTML/SVG help.

Agreed. Even simple concepts can have overly technical examples on MDN. Sometimes it causes me to overthink a simple script.

> or at least allow me to remove certain websites from my searches.

Im currently using a chrome extension from google[0] to do exactly this.

[0] https://chrome.google.com/webstore/detail/personal-blocklist...

Why is this supported through a Chrome extension?

Google is tracking everything about me. So I expect that certainly they can track which sites I don't like, especially when I mark them as such.

They use to for a short time, I don't recall if they ever said why they removed the feature from google search itself. This extension came after they removed it.

https://www.google.com/search?q=querySelectorAll+-site:w3sch...

this syntax has been supported for many years

I also like the "Personal Blocklist" extension for Chrome: https://chrome.google.com/webstore/detail/personal-blocklist...

I think the parent meant to exclude some domains from every search. I would love that too. If I have to add "-site:somedomain.com" (and maybe even many of them!) it takes less effort ignore them in the result

Bookmark that. I use the following:

https://www.google.com/webhp?hl=en&newwindow=1&num=30

I remove the ei identifier from the bookmark. I guess this is a unique ID that makes it possible for google to keep following me if I happen to bookmark it. Eg:

ei=Vo_n34buB9Cabdedfk6gO

And I happen to like the W3school examples, especially CSS. They've helped me many times. I don't see the problem with them, but please ignore them if you don't like it.

I find duckduckgo much better for these kind of searches. It also shows a brief instant result which is usually an excerpt from MDN.

Actually, I find duckduckgo better for all kinds of technical searches these days.

Their Stack Overflow integration is to me one of the best things that ever happened to search engines.

IMO W3schools has some of the best development tutorials for beginners

Some googlers made this w3fools, so employees certainly aren't fond of w3schools.

http://www.w3fools.com/

For the people who have and will comment on how bad w3schools is, Google provides a Chrome extension for blocking domains in search results.

https://googleblog.blogspot.com/2011/02/new-chrome-extension...

I don't know if there's a Firefox version.

There is https://addons.mozilla.org/en-US/firefox/addon/hide-w3school...

Can Google see your own personal list of blocked sites?

Post seems to indicate just that: "One of the signals we're exploring is explicit feedback from users."

They started with it built into search. This was probably a compromise solution to some competing internal concerns.

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 are discovering works. This is mainly because of the playground with possible implementations on top of every specification page. I hope MDN can make their site more appealing for less experience developers without cutting in on the feature-completeness.

For those interested: Behold, the W3C Schools hider extension. https://github.com/Spetnik/W3Schools-Hider

Your comment excellently demonstrates the problem with them: W3Schools is not related to the W3C in any way. Many beginners see the "W3" and think it's an official resource. This is bad.

I never implied that W3C Schools is related to W3C. But I do agree with you: that's bad. But for me that's a public secret. I don't think that's the main reason why I dislike W3C schools, though. My problem with W3C Schools is that they are not the right away to learn web development in a proper way: https://www.impressivewebs.com/w3schools-ugly-bad-good/. MDN holds a far greater standard on a whole lot of aspects: following exact W3C specs, being up to date, design, just to name a few obvious ones.

Parent thought you believe W3Schools is related to W3C because you keep calling it "W3C Schools" (it's W3Schools).

aha... right :D

Most beginners have no idea what W3C is or why they should care.

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 W3Schools, then StackOverflow, then sometimes JQuery or another library, then MDN), and you can understand where the problem lies.

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 `<li>` which, by default, has `display: list-item`, and still doesn't mention it.

I've been that less experienced developer, using w3schools would save a minute or two on certain searches. Now I enjoy going to MDN and learning a few extra things on a given topic, or reinforcing an existing understand, via MDN. Sometimes i'll lose 15 minutes crawling a few tangential links - worth.

Is there an extension to hide all the w3schools related comments in this thread?

We've marked the existing ones off-topic. That makes them rank lower on the page.

Good Bye w3schools.com ?

w3schools.com is a great resource.

I prefer it when I need a quick refresher on an HTML element because it's especially good for having short, simple examples I can copy and paste.

MDN tends to be verbose and technical. It's good when you need to know everything in detail, but often I need a quick refresher and a simple example and for that w3schools.com always seems to have better content.

Compare these two pages for input types:

https://www.w3schools.com/html/html_form_input_types.asp

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/in...

The MDN page is more complete, but reading it gives me a headache.

The whole point of documentation though is for it to be complete, technical and well explained. Not to have copy-pastable examples.

W3schools is neither good documentation or good examples though.

When I need to change a car's oil, I don't need a complete, detailed overview of the entire lubrication system. There is a place for all kinds of documentation, but exhaustive explanation is often less preferable to a quick "how do I do this."

I disagree, both are valuable. It all depends on what you need in the moment.

W3Schools is a decent introduction though.

When I was just starting out it was nice to be able to quickly look up the syntax of a basic JOIN SQL statement on w3schools.

the MDN example (unfortunately at the bottom of the page) is more correct by using a proper <label> tag with the <input> tag, while w3schools omits that detail, which makes it seem like plain text labels with <br> tags (yuck) after them are ok (label tags add accessibility among other things).

tl;dr: use <label>'s with <input>'s, not plain text labels, as MDN shows you to do.

Hi from one of MDN's writers!

So, we're aware that the examples being way at the bottom of the page are frustrating to a lot of people because of the usefulness of having a simple example you can learn from or even snag and use in your own code.

That's why we have work ongoing to not only place examples at the tops of pages, but to make the examples interactive so you can make changes to the code right on the page. There's some info about it here: https://discourse.mozilla.org/t/interactive-editors-in-beta/....

I'm glad you approve of our use of <label> to correctly label inputs. We are not yet 100% consistent about this, but we're on the job!

I find w3schools a better reference for quick HTML element and CSS rule lookup, but I always go to MDN for Javascript stuff, especially the newer API's that came with HTML5.

Hopefully - and thank God :)

Embrace...

This time around, it looks like that's where the phrase ends. Until the next CEO perhaps.

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

thanks for that. didn't realize that mdn.io existed.

It's a vanity url because it's small and can be used by tons of different orgs. Not sure why we're suddenly so sad about losing some tiny corner of the web that is very unlikely to have a huge effect irl.

I used to bookmark things judiciously 7-8 years ago, that bookmarks list is completely useless today because >90% of the links are dead, that's okay though, it's the way things go. Happens with real-world objects too, books go out of print, buildings get knocked down, not everything needs to be saved.

But people use it. You seem to think that being a web technologist gives you eminent domain over the web.

Reply on news.ycombinator.com