The problem with programming tutorials

The problem with programming tutorials on the Web is that they, more often than not, do not reference the version number of the language or library that they are covering.

Trying to find some help on the Web with a coding problem is often an exercise in frustration. I've lost count of the number of times I've found what looks like a very helpful blog post, read through it and started to implement the suggestions only to find that it doesn't compile or function properly because the post was about an out-of-date version of the thing I needed help with.

This comment on Hacker News from person2 is from a thread about the new Varnish 4.0 release and it really sums up the problem:

The biggest impact of these sorts of changes are future users who are trying to get their first configuration going, following various web tutorials. Many of those tutorials are now misleading, but via the nature of accumulated web content it won't be changed any time soon.

Lets see some examples: first up, the excellent Smashing Magazine and a tutorial about Wordpress meta boxes - a thorough and easy to read tutorial, but without version info. It does have the date at the top, it was posted in 2011 so is this still relevant for Wordpress 3.8?

Another example and another popular site, Tuts Plus on Wordpress custom post types - again, a thorough and useful tutorial with no version information.

Even Stack Overflow, the saviour of programmers the world over, rarely shows version information in its questions or answers. I recall once, whilst reviewing some changes, that one user had edited another's question and removed the version number from the tags they has added. Maybe that's SO's policy but it is madness.

If all blog posts stated in the opening paragraph the version number(s) they are referencing then the world would be a better place. Google would pick those up and that would lead to better results for queries like "Wordpress 3.8 custom posts". Even better, the posts could mark up the libraries/languages/APIs/etc they are referencing and their version numbers with Schema.org or something similar.

Tagging a tutorial with specific details and a date/time gives the exasperated programmer more info to work with but there's still the problem that the tutorial might reference version 4.X but the searcher is using 5.X so they still don't know if the tutorial is good for them. That's true, but the more information that is presented, the better the chance to make the right decision.

State your version!