Yeah for this statement, "...often Web developers are looking for quick examples...", I don't even care if the examples are higher up on the page or not...I just would like more and more examples. Sometimes the examples are too few or don't fully exemplify options of particular functions, etc. Nevertheless, I'm absolutely grateful to all the folks who put in so much work into MDN. If you are one of those people, know that I thank YOU!
This is one of the only reasons I sometimes end up back at w3schools after reading the mdn docs: when I'm looking for a quick, working, live example. A short example is worth a thousand words.
This is the kind of attitude that leads to low quality, scrappy code, akin to copy and pasting Stackoverflow; I don't believe that a developer should need a great memory but they should have a good understanding which examples do not provide. I really like that the MDN docs are well specified and hope it stays that way.
Nobody is arguing that we should be taking snippets and examples verbatim and use them 100% of the time without understanding them, just that there is value in having those snippets and examples available.
I know damn well how arrays work in javascript, from how they are implemented and what structures they use in memory at smaller sizes all the way up to the difference between a missing element in a sparse array to a dense array with an undefined value in it.
But sometimes I just want the snippet from MDN that "densifies" a sparse array. I know how it works, I can re-write it myself if needed, but I know that the one on MDN works and I won't hit any unexpected edge case because I forgot about some arcane bullshit thing.
Not to mention that when I'm first learning a new language or syntax I personally do MUCH better seeing examples of the code and being able to step through them to get the basics down (where I can then dive deeper into the system to understand the edge cases, hopefully with examples themselves to make sure I get the point).
> but I know that the one on MDN works and I won't hit any unexpected edge case
MDN is a wiki. People who want to contribute documentation or examples do so. Sometimes they make mistakes. Sometimes they're suffering from Dunning-Kruger. It is unreasonable to assume that the example will work and will not have unexpected edge cases.
It's the best resource I know on the web, which is I recommend it, and why I've contributed to it, but it's a wiki. Caveat emptor. (Caveat lector?)
An example functions as both a working piece of code, and also an illustration. I mean you might as well say ball-and-stick models are bad for chemists, because they should understand from the text alone.
There's a lot of technology to understand and absorb, and I'll take any tool I can get to help me.
APIs should be intuitive; they should be usable only from knowing their signature, and from having familiarity with similar functions. For the most part, DOM/WOM functions are like this, and so the doc will only be repeating things you could have derived intuitively. There are, of course, many situations where the use is non-obvious. In these cases it is even more important to have a good example demonstrating the idiosyncratic usage; a sidenote hidden away in the middle of the doc will easily be missed.
exactly, MDN is great, but it's too "academic" for me, it's good for reference, however I admit the time I spent on w3schools is 100x more than it's on MDNs.
Yeah, it's a great resource. I'd love to see more examples as well. Bonus points if the examples are runnable and extra-bonus points if there's a 'debugger' version that would let the user jump into a portion of the code to examine the state.
I find one of the first things I do when approaching non-trivial new features is to sketch out an example and then step through the example by adding a few strategically placed breakpoints. The breakpoints allow me to examine both the execution flow and the internal state of the various objects associated with the new feature.
Both Chrome and FF support the handy 'debugger' statement, which you can place directly in your code and which acts as a breakpoint when you run the code with devtools open.
I'd like relevant examples. It's incredibly frustrating to look at an MDN snippet to see code that no sane human would ever write. Self-executing closures that return callbacks inside for-in loops, initialization code that still checks readyState, code that avoids more than one function for no obvious reason...MDN can be a real crap-shoot. Hell, I'd be happy if they would name their variables sensible things instead of trash like `numFoo`.
Certainly there's room for more examples. Having to choose between often abstract MDN and the opposite - often zero theory Stack Overflow - is awful. I've learned to take SO with a dose of salt - you may pick up bad practices (especially for rare problems), outdated solutions etc.
I've just had to get into the habit of appending mdn to all my web development queries to make it show up at the top. Can't count the number of time's I've done the search "[some new array method] mdn". Invaluable website.
I could be imagining it, but in addition to the "instant answer" feature which uses MDN, DuckDuckGo's indexer also seems to give some priority to MDN over W3S in comparison to Google, in my experience. If W3S is first, MDN is usually second whereas it may be 5th/whatever in Google.
Which mobile browsers allow this? Does it synchronise them?
I've used these a lot in the past, but switched to DDG's bangs largely because it was such a pain to change browsers/devices, and none of them ever worked for me on mobile. DDG's bangs are still a little unwieldy (! isn't a very convenient character to type, especially on mobile), so an alternative would be nice. For now though, the consistency everywhere far outweighs any other advantages of the in-built browser feature.
In Firefox custom keywords are just bookmarks, and those sync. So this works on mobile. All you have to do is create bookmark with "%s" in the URL where you need substitution and give it a keyword, and typing `<keyword> <searchterm>` in the URL bar will use the bookmark .
Unfortunately the UI isn't too great -- on desktop, the suggestions between the awesomebar show you that a keyword search will happen (just like when you type something matching an open tab it tells you that it will switch to tab unless you hit the down arrow to choose something else). On mobile there is no such indication, but hitting enter after typing the keyword followed by the query still works fine and does the keyword search thing.
Thanks, I wasn't aware of this, particularly as the "normal" search engines in Firefox don't sync. I think this is in the works but it's been held up by some kind of issues with their search partner deals.
I was a long time Opera user up until 12 and still use the mobile version. I can't seem to use keywords on mobile though. Are you sure it works? How do you set it up?
But the second hit is a third-party source, that doesn't provide much over the plain text version. It doesn't even contain the RFC contents directly. I can't imagine anyone seriously linked to that page, let alone that so many are doing it to push it to the second place:
But you won't find that in the first 10 hits. Not even in the first 50 hits, for that matter. You will find it, however, if you click at the third item, which is the corresponding Wikipedia entry:
The very first item in the "External links" section points to tools.ietf.org.
Given the prominent low-quality links to w3schools, rfc-editor and so on, I'm asking myself if Google is actively harming Mozilla and IETF. Maybe not harming, but being ignorant. These issues are known for years. If they want to be the best possible search engine, why don't they do anything about these widely known issues? I understand that they'd rather fix their algorithms than adding special rules for IETF, but then, they should have analyzed their algorithms how they can be tricked by low-quality sites. And fix that. Meanwhile, years have passed and nothing changed.
Maybe we should introduce a new search engine:
"Second-Order Wikipedia"
It would work like this:
1. Look up the search terms in Wikipedia articles
2. For each hit, show the Links of all articles' "External Links" sections.
This is one of the clearest examples yet of why I prefer duckduckgo these days. Even if it might partially be just because less SEO is targeted at them.
Ouch! I would never have thought that this crappy site originates from the IETF itself. It doesn't even point to their beautiful (and fully inter-linked!) HTML versions.
- ietf.org/rfc/ <- this is a static version that IETF has
- rfc-editor.org <- this is the RFC Editor's official site - I think you used to be able to download stuff through FTP, and the site looked like an FTP site until recently; in some sense this is really the canonical URL for RFCs which the RFC Editor publishes
- tools.ietf.org/html/ <- this is mostly Henrik Levkowitz' work - he's working directly on datatracker.ietf.org and has for many years, I think there was a plan to have datatracker.ietf.org contain HTML versions but I don't know the status
- datatracker.ietf.org <- this is the dynamic (Django-based) site that tracks lots of stuff about the working groups and meeting and documents - the source is open so you can look at it if you like - honestly I think this is the best place to link as it gives an increasing amount of context, although tools.ietf.org/html/ is definitely the nicest way to read the contents
If your new search engine became popular, the incentive to spam Wikipedia would be enormous again. 10 years ago, Wikipedia decided to nofollow all links because of the spam for Google relevance:
I wish someone made a proper HTML RFC, with variable width characters for paragraphs for readability purposes and monospace for code (which should be easily detectable)
Me, too. However, if your opinion on W3Schools is from ten years ago when they were sketchy and misleading, it may interest you to know that it's much better now. I don't reflexively hit the back button when I land there from a search, now -- sometimes the info I'm looking for is actually there. ;)
The problem has been that historically W3Schools has been inaccurate. MDN set out to fix that and be the best source. I don't know why W3Schools has so much SEO juice.
Google sucks and you're complaining to Mozilla? I can't believe people have become so complacent with search they will start blaming great content on the internet for being hidden by shitty algorithms.
A small feature in chrome you might like, there is a quick write up about it at the link listed below. Basically configure the URL search bar for MDN to be a searchable website. Change the keyword from the full Mozilla link into something simple like mdn. Then simply when searching in the url instead of going to google.ca just type 'mdn' and space then it will use the configuration of the search query to look inside the website so something like looking to see how Array.protoype.map() works just type mdn space before that and you'll go straight to the search results.
This isn't limited to just MDN you can use it for Youtube, and other sites that support the query search string.
If you are having trouble finding the settings in Chrome to get to then simply
hit the 3 dots on the top right > settings > then at the top bar search for 'search' > Under the Search heading there will be a button labeled 'Manage Search Engines' click it > and read the article to see how to set it up.
If you have visited MDN before it will show up in the lower section. All you need to do is change the middle text box to mdn and save. otherwise the last box will need to be https://developer.mozilla.org/en-US/search?q=%s&w=3&qs=plugi... the first box is just a label used to display the search name you can leave it at default.
Firefox has the same feature. To use it right click on any search box on any website you visit to assign it a keyword. This works great with vimperator, which has tab-completion for search keywords.
Or use DuckDuckGo as your search engine, and you get thousands of those quick searches for free.
You can use !g for google, !a for amazon, !mdn for MDN, !so for Stack Overflow, etc etc. If you want to search an even vaugely popular site, you can probably just type !domain and DDG will search it.
I have found doing this unnecessary (for me) because just searching for "mdn whatever" in google gets me the MDN results I wanted as the top result with the rest of the page being populated by other related MDN results.
Not saying that people shouldn't do it. Just offering a possible simpler alternative to be tested as well
I had actually wanted to reply my original post to people discussing mdn not being the first result on a google search but I find my general work flow falls around ctrl+t (new tab) - I have a specialized extension for something on that page so it doesn't redirect me to google.ca. For a search I just type 'm' as I have it setup to be my main keyword and 'y' for youtube along with 'h' for hacker news search. And if I want to do a search from the same tab I do alt+l to get to url and I'm not losing any thought process or needing to filter through some other ad garbage coming from google when I'm in the flow, just get me to the meat and potatoes (of course YouTube and hackernews are not things I search for regularly during productive work flows ;) )
I always tell my co-workers that MDN is the de-facto documentation for JavaScript. Whenever asking a JS question, they almost always ask me to look at some crap W3Schools article. The first thing I do is always check MDN first.
Only one thing I care about: for Gods sake, remember my language preference in a cookie. No, I don't want to read incomplete docs in German. My English reading capabilities are just fine. And I certainly don't want to change the language every day when I revisit. Thanks
as a workaround, if it's ok for you to have most of the web in english, you can change the preferred language in the browser settings: you put english first and then lower priority german. I'm not sure it will work in mdn, I tried it quickly and seemed to work
I mean, they could've kept it "Mozilla Developer Network" — it's not like that doesn't sound like an online documentation resource (c.f. Microsoft Developer Network). I guess there's some ambiguity with e.g. a meetup group, but it should be obvious from context.
It's possible the name change is for SEO reasons. Although they shouldn't need to; Google really ought to swallow their competitive pride and make MDN one of their previewed snippet sources, or else create their own webdev documentation source of equal or better quality.
One thing I think could really make a difference would be wrangling the reference data into some kind of semi-structured format with an API/machine readable format like the Node docs: https://nodejs.org/api/events.json
There are a lot of documentation, code completion etc type things out there that currently rely on manual updating (eg Tern.js) or scraping (eg devdocs.io) to maintain this kind of data. It'd be good if there was a canonical source.
To the best of my knowledge, if you go to https://developer.mozilla.org you're just served articles in English (that may be because I have English set as my language in my browser, I don't remember what happens if I set it to my actual native language). But I noticed that Google search results actually are pointing me to my native language.
I'm Swedish, and get "redirected" to https://developer.mozilla.org/sv-SE/ if I follow that link, even though I have English set as the language in my browser.
2011-2015 I was on the team at Mozilla responsible for MDN.
At the time it most certainly was not doing any type of IP geolocation; your browser's Accept-Language header was how we initially determined the language to show you.
Edit: And it still does only use Accept-Language. Here's the code:
You don't get it. I don't want translations. I don't want to contribute because I don't think it is possible to translate programming code and documentation satisfactorily and I don't think it is worth trying.
If there are people who think it is, they can do it, but I just want to read everything in English when it comes to programming.
I love the resiliency of Mozilla. It seems like most news about it and Firefox are are doom and gloom, especially when we're comparing Firefox to Chrome.
So what does Mozilla do? Make their great documentation even better, and enrich the development community.
These choices by the Mozilla foundation might be unrelated. However, if things go south, I hope the community remembers who is consistently advocating for it.
MSDN has this, and I have never seen a comment there that actually provided value to a reader of the page. It makes even less sense on MDN, because MDN is a wiki; if you think something is missing, you can get it added.
Except that a lot of the time those user contributed notes are bad code that no one should ever be copy-pasting. I wish php.net had some sort of curation for those.
While the idea seems great in theory, I doubt Mozilla has the manpower to moderate it. The volume of comments would be astonishing, think Stack Overflow's Javascript tag – there are countless questions that have been answered time and again. Sorting and moderating them takes an insane amount of man-hours.
Just for reference, two years ago, during the Mozilla Work Week, one of the main problem that surfaced was that there were just a couple of people reviewing all new pages that were created and hunting for spam/illegal content
