The future of MDN: a focus on web docs | Hacker News Reader

The future of MDN: a focus on web docs

blog.mozilla.org

294 pointspaublyrne108 comments

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.

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.

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.

That's an unnecessarily broad statement.

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?)

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.

Examples are a great way to learn. Problems arise when they are the only way one learns.

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.

An example is much more effective in a lot of cases. I really wish there were more of them in man pages.

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.

Edit: Apparently the debugger statement is standardized! Neat. Didn't realize that. Thanks MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...

It's a wiki. You can edit it!

That's why I love the Highcharts.js docs[1], which redirect to jsfiddle examples.

[1]http://api.highcharts.com/highcharts

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 just would like more and more examples.

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

> Sometimes the examples are too few or don't fully exemplify options of particular functions

TBH, that's why actual documentation is there. Examples can never really cover everything something can [or cannot] do.

I just wish they had better SEO than say W3Schools

It already appears usually in higher positions than w3schools in Google, at least for me.

I remember there was an effort to get related tech sites and blogs to reference MDN over W3Schools to attempt to get it higher in the search results.

I installed "Personal Blocklist" extension exclusively for w3schools...

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

Same for RFCs.

Let's search for "rfc 1855". The first item is indeed the original plain text source, unfortunately without links or anything:

- https://www.ietf.org/rfc/rfc1855.txt

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:

- https://www.rfc-editor.org/info/rfc1855 ... wtf?!

Moreover, the RFC authors group itself, the IETF, already provides a beautiful HTML representation, with links and everything:

- https://tools.ietf.org/html/rfc1855

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:

- https://en.wikipedia.org/wiki/Etiquette_in_technology

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.

Same search on duckduckgo, first few results are (in order):

- https://tools.ietf.org/html/rfc1855 (html version)

- ietf.org/rfc/rfc1855.txt (text version)

- rfc1855.net (another html version which is more readable than the ietf's)

- datatracker.ietf.org/doc/rfc1855/ (information about the history of the rfc)

- https://www.rfc-editor.org/info/rfc1855 (useless)

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.

On DDG, you can use a bang search to directly get there too. Try: !rfc 1925

rfc-editor.org is an IETF-run service and is the official permanent home for RFCs now. See https://www.rfc-editor.org/info/rfc7990

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.

That HTML RFC page is one of the few pages I've ever tested with PageSpeed (by Google) that gets 100/100 marks for Mobile and Desktop versions!

https://developers.google.com/speed/pagespeed/insights/?url=...

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)

Work started on that last year based on the RFC XML format. Or was it the year before that? It will get here eventually.

I think it's likely someone will go through old RFCs and convert them too.

I'd be quite happy with markdown.

FYI, to the best of my knowledge:

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

https://www.searchenginejournal.com/all-wikipedia-links-are-...

i just add mdn at the end of my query.

Am I the only one who prefers W3Schools over MDN? It's much less cluttered and immediately gives me the example usage I'm looking for.

I find both to be very well done but MDN goes in depth the most.

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.

Historically maybe but I don't think that's true nowadays.

Even then, why would you support a closed, commercial, outdated website instead of MDN which is essentially a wiki?

The same reason why beginners get a sentiment of attachment with websites like Stack Overflow.

They're looking for "how to do <something>", not for the docs.

Depending on the topic, I often get MDN above w3schools. And adding mdn is not much of a bother.

They show up pretty high on DuckDuckGo. I think W3Fools has more traffic and more hyperlinks from the DHTML years.

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.

Same. Maybe I'll make a point of not appending the "mdn" and just scrolling down until I find the MDN result, in the future.

In firefox you can also add it as an alternative search engine.

You can do that in pretty much every browser, and also add a search keyword (e.g. mdn), so you can do "mdn array" to search the MDN site for "array".

If DuckDuckGo is your default search engine, you can just do

    !mdn <search query>

and get the MDN search results page.

You can also do the same for stuff like

    !gweek <search query>

And get google results limited to the last week (or StartPage ones if you swap the g for and s).

It's amazing.

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.

Any reasonable web browser lets you assign keywords to searches. No need to go through a third-party.

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.

> Which mobile browsers allow this? Does it synchronise them?

Opera, yes.

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?

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.

I might try to fix that.

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.

Using DDG is an awesome, ethical thing to do. The fact that it's actually got perks over Google is just the cherry on top.

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.

happy searchin!

https://www.wired.com/2013/09/h2-chrome-omnibox/

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.

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 ;) )

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.

https://ddg.gg

I don't remember who built it, but MDN.io is a neat little tool that allows you to quickly jump to the MDN docs for a given topic.

For example: http://mdn.io/flexbox

Admittedly, I don't use it, but cool that it exists!

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.

Any extra love and attention given to what I'd consider to be one of the greatest resources out there for web developers is great news to me.

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'd guess they could have kept the acronym to mean Mozilla Documentation Nexus.

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.

We're working on this... https://github.com/mdn/browser-compat-data, https://github.com/mdn/data ...but it's going to be a slow process.

Please stop forcing those stupid horrible-quality Portuguese translations upon me!

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.

English is my language in my browser, but they seem to be using IP addresses, because sometimes I get Portuguese articles.

They should keep an endless cookie or whatever to never serve me anything besides English.

They automatically set it according to your location, I have the same problem in France.

if you don't want geo location for other reasons, you can turn it off :

https://support.mozilla.org/en-US/questions/1002846

This "geo.enabled" flag should be false by default on desktop Firefox! <<PRIVACY HARUMPH>>

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.

I'm Swedish and I don't get redirected. Are you sure Swedish isn't listed in (firefox) Options -> Content -> Languages -> Choose... ?

(the language of the browser itself is irrelevant)

It's embarrassing how many steps you have to take do this. Why not honor my OS settings huh...

I'm on Chrome, and even though both my OS and browser is set to English, I do get redirected to the translated page.

Thanks for the heads up though, I'll do some more digging and see if I can manage to change it.

I don't get redirected in chrome wither, granted I always need to relentlessly hunt down obscure language menus.

Perhaps: Settings -> Show advanced settings (sigh) -> Language and input settings

Ugh, you have to drag and drop order in that list. Top-to-bottom priority. Now it works.

Tack för hjälpen!

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:

https://github.com/mozilla/kuma/blob/a3ad0dbb286fd45affdf1ae...

Thank you, I'll look deeper and see if I can solve it. It's likely an issue on my end then, I've corrected my comment.

It's boring since we have to click the english version but led me to improve the translated version sometimes.

To every native English-speaker on here: If you do this on your site words cannot describe the agony you cause your users.

Not that google listens but they are a huge offender in this area.

Oh, automatic translations, or translation made by crappy stupid people, I hate you so much!

https://developer.mozilla.org/en-US/docs/MDN/Contribute/Loca...

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.

One thing that would be brilliant and would also help with numerous other issues would be if the site was open source and available on Github.

This change would allow numerous improvements such as up-to-date, relevant examples, issues and pull requests for discussions and improvement etc.

MDN is a wiki, so you can in fact fix problems you find.

Discussion is done via mailing list.

Is it actually editable again?

Last time I tried to edit an obvious error in the page the edit button led to a page telling you to create a ticket in bugzilla.

Looks like the code is on github at https://github.com/mozilla/kuma

By the way, whatever happened to real web doc formats being established, like something that could one day make obsolete Ms word addin and PDF.

Keep up the great work MDN! You're truly a life saver.

Can we please have a comments section on every page of documentation?

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

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.

i like php.net's "user contributed notes" system:

https://secure.php.net/manual/en/function.htmlspecialchars.p...

https://secure.php.net/manual/en/function.preg-replace.php#u...

https://secure.php.net/manual/en/function.header.php#usernot...

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.

MDN is a wiki. If something is wrong or could be improved, you're empowered to fix it directly. :)

I don't know why this was done years ago instead of that web platform push.

The Web Platform was a great idea and had Adobe, Apple, Facebook, Google, HP, Intel, Microsoft, Mozilla, Nokia, Opera, and the W3C as stewards.

Unfortunately, it may have been politics between some of the companies that prevented a real success.

The good news is that we will revive the web platform on WebPlatform.Com as part of OpenDomain - anyone that wants to participate is welcome!

There is [edit: was] also a community-driven alternative to MDN: https://webplatform.github.io/docs/

Discontinued in 2015. Why would you recommend anyone use that site?

Maybe because they didn't know? Sheesh.

MDN is community-driven.

Source: I was part of that community for more than a year (first as a translator, than as a topic-driver).

Sorry, I meant "community-driven as well as MDN". English is not my mother tongue.

Reply on news.ycombinator.com