- 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:
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!