
The future of MDN: a focus on web docs - paublyrne
https://blog.mozilla.org/opendesign/future-mdn-focus-web-docs/
======
mxuribe
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!

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

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

~~~
Klathmon
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).

~~~
jholman
> _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?)

------
westoque
I just wish they had better SEO than say W3Schools

~~~
vog
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](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](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](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](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.

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

\- [https://tools.ietf.org/html/rfc1855](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](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.

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

------
alunchbox
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...](https://developer.mozilla.org/en-
US/search?q=%s&w=3&qs=plugin) 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/](https://www.wired.com/2013/09/h2-chrome-omnibox/)

~~~
flanbiscuit
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

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

------
md224
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](http://mdn.io/flexbox)

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

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

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

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

~~~
scotu
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

------
klez
I'd guess they could have kept the acronym to mean Mozilla Documentation
Nexus.

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

------
sgentle
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](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.

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

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

~~~
klez
To the best of my knowledge, if you go to
[https://developer.mozilla.org](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.

~~~
Svenskunganka
I'm Swedish, and get "redirected" to [https://developer.mozilla.org/sv-
SE/](https://developer.mozilla.org/sv-SE/) if I follow that link, even though
I have English set as the language in my browser.

~~~
ubernostrum
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...](https://github.com/mozilla/kuma/blob/a3ad0dbb286fd45affdf1aec329704ed90b2b6c5/kuma/core/urlresolvers.py#L118)

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

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

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

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

Discussion is done via mailing list.

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

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

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

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

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

~~~
uwu
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.htmlspecialchars.php#usernotes)

[https://secure.php.net/manual/en/function.preg-
replace.php#u...](https://secure.php.net/manual/en/function.preg-
replace.php#usernotes)

[https://secure.php.net/manual/en/function.header.php#usernot...](https://secure.php.net/manual/en/function.header.php#usernotes)

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

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

~~~
opendomain
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!

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

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

~~~
nailer
Maybe because they didn't know? Sheesh.

