Anyone else think MDN code descriptions/samples suck?


Yeah good point for sure. Ya cant learn to code as quickly if ya don't work through it on your own - which is really the point of the exercise.


I feel the same, I always look up on a W3 example first, because they are so simple and simply shows the most common usage of the function you are looking for.

However I think MDN can have it's place if you need to look further into something, but I prefer not to as it's very dense.


Sure. Everything we write will be Creative Commons licensed. They can choose to pull some of this back in if they want.

Unfortunately, the MDN uses a wiki-type editor instead of a code repository like we are, so there's no way I know of to simply fork the MDN, and there may not be a way for them to play back our changes on top.

I really do think the best way is for us to just write our own articles.


Sounds good! It will be nice to see how our Wiki improves :ok_hand:


Glad to see I'm not the only one who's struggling with MDN. Like you, I prefer W3schools and StackOverflow. I also frequently (re)visit Codecademy to enlighten me (all over again and again).


This my came a bit late.... however I feel I must make justice for the documentation of MDN... I now it my be a bit confusing in the beggining to understand the documentation, but i strongly encourage to spend some time to understand it.

MDN documentation my be more formal but is more accurate than say w3schools.

Here you can find a link to help you guys to understand the syntax used in MDN in CSS for example.


I'm a professional developer and my biggest tip to new people is write about these functions in a way that you'd understand. Hop on github, make some basic blog or website and write descriptions and use cases and such. For one, you'll be helping other new coders and it'll help you learn.


I'm going to go a bit against the grain here and say I love MDN.

No, it's not a tutorial.

No, it doesn't always have a step by step guide to using a particular method to do what I need to do right now.

However, it is flat out amazing when you think of it in a different light - as a research tool to enhance your exposure to the myriad of what's available "out of the box". For instance, read through the "String" entry on MDN and you'll find a list of the methods available to you when you're working with strings. Sure, you probably already know toLowerCase() and the like - but there's dozens of other methods. Awesome methods that you can use to do a wide variety of operations with strings just by using an existing method instead of having to write one yourself.

There are tons of books and other web sites out there, but for detailed, comprehensive information - to my mind, MDN just wins. Especially when I proactively use it to review what's available instead of looking to it to have a code sample to solve my current problem.

But, then again, I enjoy reading, read quickly, and tend to look to MDN more in search of questions than answers. Questions like "Wow, I can do that with CSS?" came up a lot when I skimmed the CSS section. There really are a ton of things CSS can do that just don't get covered in other literature.

If I could encourage everyone at FCC to do just three things, they would be:

  1. Read MDN for 30 minutes with your morning coffee/tea/whatever - not looking for a particular solution, look at the Reference pages and just browse through to pages that make you think "wow". Get familiar wading through the vastness of what's available. MDN will help you see the big picture if you think of it as a gateway and not an answer-bot.

  2. Learn how to test your code. By writing tests that run automatically when you change your code. Test everything.

  3. When you're burnt out on coding but still have 30 minutes free time, spend it at Khan Academy. Don't believe the people who say you don't need math. The more math you know, the better you become at solving complex analytical problems, and that's what software engineers do.


OMG yes a thousand times!!! I have felt the same for years! I can't stand them. You are exactly on point. Ridiculous examples to explain a simple statement and written in the most reader-unfriendly way possible where it takes me three times longer to figure out how to use something than W3S. Ironically, W3S gets a ton of flack and gets dissed at every opportunity just about everywhere I've seen their name mentioned, but dammit, their examples are quick and easy!

The problem with W3S is that they aren't really complete in their explanations and that's where MDN wins. But geez, wading through all that mud to find the nickel barely seems worth it.

The things is though, that MDN is a reference. Great, but if that's the case, people need to stop suggesting it as the #1 option for newbies to learn with. It's just not. I'm not even really a real newbie and I still find it a hard read. That said, I am finding that recently, I'm getting more comfortable with it and if I'm looking for completeness, I'll go there first.

P.S. FCC needs to add a "superlike" for things like this. LOL


MDN is extremely hard to understand. When I have something that is really important to me I copy the text and that revise it using the common words to make sense of the text, otherwise it is so confusing, as authors often while explaining a simple concept connect it to a far away advanced concept with wording that makes you feel like you never even knew English at all :disappointed_relieved:


It’s just MDN is totally beginner unfriendly. You must know the meaning of all those keywords and get its meaning in the context like: callback, arguments, index, element, thisArg


The MDN is design to be “technical” so technical that hardly anyone understand. For beginner the definition of a pre defined function usually don’t make sense. The same idea can be rewritten with simpler term and with less words, I simply don’t get these technical writer or “programmer” who need to spill big words in every sentence to feel better about themselves.

W3school has way better definition and straight forward examples.

If these same people who write the MDN are the people that defines the standard, we can see why they make so many complex idea in the name of robust when it can be written using a simple for loop.

I am just venting now. Lol


Yeah, agree. Most of the time I found the articles on MDN are really hard for me to understand. So I need to refer to other resources to find the answer to the problem.


I actually really love the MDN and use it as my main go-to reference.

It’s definitely not a set of tutorials or hand holding for beginners. Nor is it meant to be. It’s a comprehensive reference (like a dictionary or encyclopedia). And as such, it should not - with every definition and article - seek to re-define the most basic of terms. That would cause massive bloat in every article. Instead, it is up to the user to educate themselves to the level that the tool is useful.

The good news is that MDN also provide beginner materials:

and …

(I haven’t used those so I can’t comment on their quality).

A dictionary does not aspire to teach you to write a novel. Nor does an encyclopedia. They provide knowledge in a structured, searchable/discoverable format. The modern versions on the web allow for easy linking and deep dives via links like the paper versions never could.

There is tons of material for beginning coders. The MDN is meant to simply set out to define terms and capabilities. It is then up to the developer to combine those into constructs (a program!) which does what they want them to do.

When I want to look for something up related to Javascript (a method, or API) I always include MDN in my search terms so that I am more likely to end up there.

@P1xt’s response from June '16 is right on point. Use it as a tool to explore. I can’t count the number of times I’ve run across a method/API while browsing the MDN that I hadn’t heard of. Even if I don’t explore it in full right then, I now know it exists and can go back to it later when I want to use it.

It comes down to using the proper tool to help solve the problem you are faced with.

If you are brand new to programming and to Javascript, trying to dive into the middle of an MDN definition of an Array method is going to be a steep learning curve (What’s an array?, What’s a callback?, What’s this?, What’s index?, etc.). If you don’t understand what you are reading there that simply means you’re missing some foundational information - not a bad thing at all - but further study is required to get up to the point where reading one of those articles is comfortable and easy.

Once you reach that point, I think you’ll be thankful that every article doesn’t re-define basic terms before getting to the point.



I don’t think MDN is necessarily a good resource to learn from as a beginner, but it definitely doesn’t suck. It’s definitely my go-to reference and I almost always have a MDN tab open when I’m working.


Indeed, MDN is excellent - the whole point of documentation is for a description of what’s available and a terse example of how to use it (if it’s not already obvious from the docs). It’s supposed to get you up and running, not teach you how to build something complex. Plus, there may come a day where you wish you had a deep technical explanation of how the code works…but it won’t be there.


It’s something you warm to with experience, I think. When I was starting out, I thought W3Schools was fantastic and couldn’t make sense of a lot of MDN material. Nowadays, I appreciate the detail and precision of the MDN documentation, while W3Schools appears too superficial. Keep learning!


I some many cases that web make me confuse


I’m 100% agree. It’s difficult for beginners to jump in easily.

But here’s a trick:
MDN has really good tutorials.

It’s a good idea to start from scratch even if you have some experience. The more experience you have the faster would be your progress. Repetition of the mother of learning.

Even tho I had experience in web and some experience in JS, I started from here:

And that was totally easy, refreshing, helpful and cool.

That’s I guess how MDN guys expect you’ll get used to their explanation patterns.
Hope it’s helpful.


The important thing here to notice is that in general documentations use a very strict language. The goal isn’t to be emphatic towards newcomers, it’s to describe with precision the tools available.
As a newcomer, the effort of getting used to reading documentation is inevitable. MDN keeps it all in one place, and the code samples go a long way towards helping newcomers.

Keep in mind that, while you can’t fully understand the documentation, you don’t have to use MDN. Use whatever works for you and, as time goes by, you will naturally seek MDN for the reasons above.