Anyone else think MDN code descriptions/samples suck?


#21

@Jayster I also had a similar feeling. Mainly I struggled with reading their syntax. It is great how detailed they are but sometimes I just want a bare bones way that just gives the gist of a method.

What I ended up doing and found helpful was as I go along I write down each method used into a personal desktop wiki. I rewrite a method in a way that makes it easier for my brain. So str.charCodeAt(index) become var utfCodeNum = str.charCodeAt(indexPos);


#22

Cool! Didn't see their tutorials section before. Thanks for linking to it. I'll check it out. :slight_smile:


#23

Oh dang... that's a really good idea! :slight_smile: I may try that. Plus, by the time yer done (or after a good amount of time anyhow - you'll have created a really valuable resource to share with others. Pretty smart!


#24

I agree... those descriptions man... lol Thanks for your feedback! Good to know you get it too! Seems like we are far from alone on this one, which is really what I was trying to find out.

I just always think a simple code example is better - no matter what level yer at - so the concept is conveyed efficiently - and the coder can take it and do whatever highly complex thing they need to do with it from there. My brain is typically pretty fatigued at the point where I'm referencing something - so having to brain through a long example is even more fatiguing (probably my key aversion come to think of it). MDN code samples seem to want to take it there right away for you - making you view the concept in an environment of added complexity. Just not my thing I guess. Maybe later down the line a bit (we'll see). :wink: I mean... if yer looking up a method, you obviously have some degree of unfamiliarity with it, right?? So, kinda levels the playing field a bit. They should always target simplicity (I think).


#25

Good point - "suck" is likely a strong term. lol I go right for the jugular sometimes - especially when a resource frustrates me. But like you are a few others have said - maybe with more time in the game I'll change my tune... :wink:


#26

@Jayster thank you for bringing this up, and thank you everyone else for chiming in with your candid opinions.

I see our wiki as an opportunity to create more beginner-accessible documentation. Our goal is not to replace the MDN, which is quite in-depth, but to create our own beginner-friendly reference.

I've created an issue with a checklist of all the MDN's JavaScript articles and links to each of them. We can rewrite them in simpler wording (without as much jargon) and use more straight forward examples.

If you all would like to help us do so, we would welcome your contributions! The MDN uses the same creative commons license we do, so don't worry about plagiarism.


#27

Actually, DevDocs.io uses the MDN as its JavaScript reference. These are the exact same articles you'd find in the MDN (I just verified this myself). I do love DevDocs, though.


#28

And I would still encourage giving back to MDN when one is able. They do have tutorials for beginner's, and in paricular the entry-level HTML and CSS sections are incomplete. Perhaps if FCC Wiki receives a lot of attention and effort , another project would be to share this with MDN?


#29

I don't think they are that bad. I definitely have to read and try the MDN examples a few times before I "get it" but the information is typically useful. I'd say StackOverflow is much worse! I find a question that sounds exactly like the one I have and then underneath it are 15 different answers, many of them disparaging someone else's answer or telling the person the question has already been answered somewhere else and they need to look there.


#31

Good point, for some to say StackOverflow is a better resource than MDN is like comparing apples to oranges. Both have a different purpose and with completly different standards. You can get answers at StackOverflow, but often they will be even more obfuscated and confusing than even the supposedly difficult MDN documentation. Or sometimes not, if you are lucky :wink:


#32

Yes I do feel the same way. Especially when I really need to know how to use a library. I've brought this up before in chat and was kinda of ignored. It's good to know that others feel the same way.

Dom


#33

Still not sure how any of this is the fault of MDN. This topic has become of great interest to me...


#34

I especially had trouble understanding things like call, apply, and bind on MDN. There seems to be very little explanation written about certain topics.


#35

Good topic.

After digging into each MDN, W3 and StackO in order to solve a problem, I usually land on a solution. But if I had to rely solely on MDN, I'd lose my mind.

I applaud the MDN team's effort and dedication, but like the person mentioned up-thread, I make my own simplified, local wiki/slide deck/anki flash cards for the most common JS methods, statements, etc. It's a lot of work, but I make the time.


#36

@chadwyck242 I don't think anyone is faulting MDN. I think the issue is just a mismatch of resources to skill level. A novice doesn't want a lot of information, they want just the right amount of information that applies to their current context(why in person teachers are great), which I imagine is the algorithm challenge they are working on. Instead of the usual detailed document they might just want say this.

I think a great solution was what @QuincyLarson mentioned earlier, the FCC wiki. That being said it looks like I have some contributing to the wiki to do this week. If anyone wants to collaborate with me, send me a pm on gitter to @dogwaddle.


#37

@theDigEx me too. I search once ( I try to do this anyway... ), find the best examples and answer I can, and add the solution to my notes I maintain in Notepad++. I keep a running file for HTML, another for CSS, another for Javascript etc...

This seems the optimum solution. And writing it down in note form is a well known technique to aid memory.


#38

Man Quincy... yer all over it!! :slight_smile: Thanks for this, and yes - that's an awesome opportunity to contribute to a great project in FCC!


#39

I know right?? Those guys over there at Stack are really punchy about the "subject already covered" thing lol. Pretty ruthless crowd. Forums can get kinda weird for sure - like a sub culture thing. What I do like about Stack tho - is that there are soooo many examples - lots of times you can find something that is pretty spot on to the problem at hand. But outside of those instances... yeah I agree... it can become a real time sump to browse all the various suggested answers etc.


#40

That's actually why I try not to use SO too much in a learning environment: I've had too many times when I was searching for something, rather than getting advice/direction they just give the solution.


#41

@dogwaddle Good luck with the Wiki, I may look at it this weekend and see what @QuincyLarson was mentioning. It would be something worthwhile to contribute to, and then take that experience and contribute over at MDN someday.
Maybe people are not faulting MDN and the documentation teams, but it can come near to it. Hopefully learners know they need to be flexible and very curious when exploring a topic. MDN is certainly not the only place to turn to for help, and finding resources as a programmer is a skill unto itself, but I do think that some learning material MDN offers is being missed by some students. Maybe they need to redesign the portal for learning materials?? Who knows.