Christian Heilmann

Posts Tagged ‘learning’

Promote better JavaScript documentation with PromoteJS

Sunday, September 26th, 2010

As I heard during my visit in the valley last week and just now from the goings-on at the JSConf in Berlin, Mozilla is working on ramping up the already amazing MDC documentation for JavaScript and you can help by providing some guerrilla SEO - simply add the following image with the right code available at http://www.promotejs.com/ to any article that talks about JavaScript:

JavaScript JS Documentation: JS Array splice, JavaScript Array splice, JS Array .splice, JavaScript Array .splice

The reason is obvious when you search for the term “JavaScript” – the things you find are wiki articles or even products that tell you not to care about learning JavaScript when you use them. As the term JavaScript was a hot SEO term during the DHTML days and with the resurrection now a lot of sites washed out the experience of finding something good when you try to use the web to find it. When I wrote my JavaScript book Beginning JavaScript with DOM Scripting and Ajax I had a chapter that told you where to find good information about JavaScript and other than the MDC and SelfHTML (if you are German or Spanish) I drew quite a blank. Lately Sitepoint started to put together some good docs but then all we had was W3Schools.

Let’s shine a Flashlight on the elephant in the room: W3Schools. This site is the number one for almost every technical search term in CSS, JavaScript and HTML. There are a few reasons for this:

  • Its SEO is spot on – heading structure, amount of links and deep level content (long tail)
  • It leaves you with a good feeling – “oh this is how simple it is! Cool, no need to read more, just copy and paste the example and I am an expert”
  • It is fast and small

The “good feeling” part is also what makes it dangerous. I ranted in several talks about the Siren Song of W3schools – it gives you the what but not the why. You can use it as a reference when you already know your stuff but it is dangerous for people to learn a subject matter. Programming is not about syntax alone – it is also about the environment you apply it in. W3schools is like bringing up your kid on fast food – quick, fast and cheap. This is not the fault of the maintainers of W3Schools – it is the fault of people sending new learners there for information.

The PHP docs are a good compromise of fast information with insights from implementers in the field – I learnt more from comments on the docs in PHP than from the entries themselves.

In the write great code examples chapter of my Developer Evangelism handbook I described a blueprint how to write a code example that explains and educates. Sadly this takes much more work than just showing the syntax. And this is why the docs sites that simply tell the “how” are winning – they update much faster with less overhead.

It is very cool to see Chris WillisonChris Williams(DOH!) and others take on the challenge and Mozilla to me is the perfect host for this kind of effort – they are open, independent when it comes to JS and have a track record of providing good docs.

Interestingly enough about five few years ago I tried a similar approach for all docs:

Replacing old tutorials with new ones - Obsoletely Famous by photo

Other than getting it hacked once I found no support for it though so I shut it down a year ago. Now with the leading names of the market talking about a similar thing at the leading conference of the language we have a better chance. Help us!

view-source will teach you things that are wrong

Monday, August 23rd, 2010

Lately I find more and more people in comments fighting for the need for “view-source” in our web products and claiming it to be a “vital part of the open web” and a “great way of learning for new developers”. This ails me as it is in my point of view a very outdated idea of learning and building web sites. I am not saying that view-source is not important – I am saying that there are better ways of learning and analysing code.

When view-source was king

Back in the days when I started working on the web you learned by looking at the source code of other peoples live web sites, copying and pasting what they’ve done and reverse engineering the workings to see how you can use or improve it. This is how I learnt JavaScript as there were no free blogs, tutorials or articles out there to tell me. The books available (basically the JavaScript Reference) dealt with the technologies themselves and not their application in a browser world. JavaScript for example was still considered a toy language in comparison to the mighty Perl or ASP or PHP or Java.

A few years before the web I learnt Assembly Language by analysing games on my C64 and trying to get endless lives. I did this by freezing the game, checking the part of the screen that changed when I lost a life (the counter) and then hunting through the memory to find the code that altered the counter on the screen (finding the DEC). I learnt how to cheat the system – not how to write Assembly Language. That came later when I had spent a few years reverse engineering.

That kind of commitment we don’t have time for if you want to learn web development.

View source gives you a view and not the source

Despite the time spent, the problem with looking at a web site with view source is that you don’t see the source, but you see a view:

  • If you build web sites with performance in mind and in high end environments you send browser-optimized views to different browsers. This means that learners would see what is optimised for Firefox and then try it out in Safari. Or worse, they see what we need to jump through to make old IEs behave and consider this the best way of developing.
  • Live code is normally minified and concatenated and has comments removed. So you learn the how but not the why. Some of the things you see might be terrible hacks but necessary for the environment used to build the web site.
  • Checking generated source is even worse. Browsers add browser-specific code that the original writer never added.
  • Live web sites are normally built by committee and have a lot of things in them the developer feels dirty about: tracking codes, third party ads with ridiculous code quality, quick hacks to get the thing out the door at the agreed time and date.
  • Most web sites these days are not written by hand – if you build for the web and you don’t use the power templating, CMS and databases and web services offer you are missing out on a lot of great opportunities. HTML is the end product of a methodology and a build process – not the start of it.

Open source is the new view-source

If you really want to learn about how web sites are built and how to use certain technologies, look at the source code repositories instead. GitHub, SourceForge, Google Code and all the others are full of great examples. This is where developers communicate with each other and show off the newest technologies.

As the final product is created and not written by hand you will find the important comments as to why something is the way it is there.

Say my entry to the 10K competition World Info. If you look at the source code you will see minified JS and CSS, all of it inline. I would never code that way. This is the result of a build script. I tell the world that:

World info source code message by codepo8

If you look at the source on GitHub you get step by step comments how I have built the solution.

What would a new learner get more information from? This was not much more work for me – as I document where I write I keep things up-to-date. Even more interesting, I actually fixed a few problems and change my code while I was documenting it – as I was forced to look at it again from a different angle after having written it.

Learn the why not only the how

The main problem with teaching people how to become good web developers is that there is a massive lack of patience. Instead of realising that knowing the syntax of a language doesn’t make you a developer we think this is all that is needed. It is like learning the grammar of a language and then trying to communicate without having the vocabulary. Or analysing the syntax of a poem without looking at the metaphors and their meaning or the historical environment it was written in. Most of what makes development and writing art and craft is lost because of the lack of patience.

W3Schools is a great example. It tells you the quickest solution and gives you something to play with. This is why it is massively successful. It is a terrible resource though as it doesn’t explain what can go wrong, when this would be a bad solution and it gives people the idea that they know everything by knowing the syntax. The PHP documentation is better as you learn in the community comments how to apply the functions and how they fail.

If you really want to learn about web development and standards then there are a few very good resources:

And far too many personal blogs that I could list here now. None of these are 2 second lookup tasks – but once you went through some of them you will know the why and the how and you will be able to see what is sensible to take on from a source view and what is probably not that a good idea.

TTMMHTM: New evangelism handbook chapter, safe browsing, challenging IE6, free teaching resources and an answer to the question if hamsters can be milked

Monday, August 3rd, 2009

Things that made me happy this morning:

It is official, I am an ELF

Thursday, November 29th, 2007

No, I am not talking about last year’s elf yourself viral pest, but about being an Excellent Learning Facilitator or ELF. This is a training for trainers which turns a lot of your beliefs about teaching and training inside out and by doing so makes you a much better trainer. I normally don’t talk about personal stuff here, so sorry if you expected another JS posts, but I really wanted to talk about this as I think a lot more people should go for it and I am proud to have pulled it off.

The ELF course is held by the UK company Matrix42 and has a lot of cool benefits:

The ELF courses are mapped to the National Occupational Standards for Learning and Development
The Bronze assessment is accepted as evidence of competence for professional membership of the Institute of IT training, as recognised by OCR at Level 3 equivalence on the National Qualifications framework
It is also one of a few qualifications to be endorsed by the British Computer Society (BSC) against their ACTT qualification which is a level 4 qualification on the National Qualifications framework

Beats me what a lot of that means but what I took away from the course is basically that it:

  • teaches you how to make learners find solutions themselves instead of listening to you (thus remembering a lot more)
  • makes you aware of the different kind of learners and how information should be conveyed to them to be easy to take in and to stick
  • teaches you to plan a full learning event and sessions in those to be as useful as possible for the participants
  • makes you aware that you can teach really complex technical courses without computers or monkeying about in front of a powerpoint.

My personal win was to get away from the speaker that I normally am and switch to trainer when I need to. Not everybody who gives public speeches and writes books is also a good trainer, actually it is quite a step from one to the other and you need to set a massive switch in your head.

In my case I messed up my first practical test exactly for that reason: I was more of a presenter than a trainer which made me rush participants. Silence is not a problem and if neither you nor participants in a training talk this does not mean nothing happens. In the heads of the participants there is a lot going on. I changed my pace and stance and voila, the second time I passed with flying colours.

Anyways, I am proud to be an ELF, and I will try my best to use this new approach and ideas as soon as I can bag another workshop or longer training session.