Christian Heilmann

Posts Tagged ‘teaching’

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!

Enjoying the full stack – my talk at Frontend2010 in Oslo, Norway

Friday, September 3rd, 2010

I just got back from Frontend 2010 in Oslo, Norway. Two days of excessive drinkinggreat information about designing and building the web of tomorrow.. I was invited as a speaker alongside a lot of great people and my task was to give the last presentation of the conference to sum up a bit what we had heard about and what to do with it when we get back home. And this is what I did. Here are the slides. More to come later when the video is out and I am not using my almost empty Nexus as a hotspot as the British Airways wireless is FAIL again.

Chris Heilmann the mild mannered speakerChris Heilmann the revengeful norse god

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:

Is it getting harder and harder to show very easy examples?

Tuesday, April 7th, 2009

I am right now teaching a four day class of DOM and Ajax in Sunnyvale, California and also do some tech editing for Scriptin with JavaScript and Ajax by Charles Wyke-Smith and I find one thing that is pretty worrying: easy examples of web development practices are dangerous to show these days.

I’m talking about practices that make it easy to get quick results and give readers and attendees “I am getting this – this is easy” fuzzy warm feelings.

One very obvious example is form validation and re-rendering of a form using PHP_SELF and displaying user data using $_GET or $_POST. Unfiltered they are a free invitation for any XSS attack and will turn your server into a spam-hub or bot-net drone. Explaining countermeasures of XSS normally is out of scope for an example that only shows how a form would work that you enhance progressively.

The same applies to simply outdated ideas like onevent handlers. It is easy to show an example that uses a few onclick handlers, but explaining event handling really well takes a bit of time. Again, this is something that really does not fit in the scope of a DOM course.

I do however think that it is important to get it in there, as there is no such thing as knowing one technology in the web development stack and being able to use it. There’s a lot of overlap with other areas and in order to be a good developer and play well with others you need to be aware of your effects and areas of overlap with your colleagues’ skill-sets.

The other extreme I find myself doing is being too over-cautious. I went through the tough times of the first browser wars and got a deep-rooted mistrust towards anything some browser tells me is OK to do and use. However, I get the feeling that it doesn’t really matter any more if Internet Explorer has a problem with name vs. ID or whatever other shenanigans we have to be aware of when we build things from scratch.

I do get the distinct feeling that not building on top of a good client-side library is simply a waste of time these days. Libraries allow us to write code, not to work around bugs and wonder what other safety measure we have to put in.

That’s why I started asking people in my courses to use Firefox with Firebug and use a good text editor to code along. Today I managed to breeze through how to write HTML that is ready for internationalisation and works with assistive technology, over simple DOM access to the document and at the end writing a validation script for a form using generated DOM content. By concentrating on how things are meant to work instead of debugging random issues I managed to get the students to reach far into the matter in a day – even those who never touched JavaScript before.

Maybe it is time to get beginners accustomed to a market that builds on working solutions and benefits from browser abstraction via libraries than teaching developing from total scratch – bad browsers and bad people taking advantage of any technology to gain access or spam us seem to have made this way of working redundant.