Indicate what version of jQuery the tutorial is stable for

[Incognito]

There needs to be an indication for consumers and contributors what docs are out-of-date, or possibly unverified as working in a major version.

We already face this on the internet we have lots of legacy code that says things like the right way to use jQuery is change .attr() or set .live() handlers. That's not good, and people learning will start using them instead of doing the correct thing.

There's a lot of canned reasons I can come up with at will for why this is an easy and obvious thing to do, but... does anyone else agree?

[rwaldron]

This site's tutorials should always be with the latest stable release of the library. If that's not the reality, then it's a bug and should be filed here. Otherwise, the jQuery API docs always have precedence over tutorials across the web; using your example, I can easily learn that .live() is no longer part of the library by simply looking here: http://api.jquery.com/live/

[rmurphey]

I agree that this should be clearly stated, though I'm not sure the right place to do it. Perhaps on the home page?

I think the goal is that the learning site should reflect the current version of jQuery. Making that goal a reality may be an obvious thing to do, but it's not necessarily an "easy" thing to do :) It will require a) reviewing the site to ensure all content is up to date with 1.9.1 for now, and b) continuing to review and update the site as new versions are released. A lot of effort has gone in along these lines, for example to ensure that .on() is the "blessed" way of working with events, and that the differences between .attr() and .prop() are accurately described.

Of course, none of this addresses developers who are stuck using an older version, which is often the case. People still using 1.4 are not uncommon, and people using 1.2.6 are not unheard of. I don't think that's a problem that this guide can solve in the near term, though.

All of that said: as @rwldrn wrote as I was typing this, if you see any cases where the current content is out of sync with the current version of jQuery, by all means open an issue!

[Incognito]

@rwldrn I don't feel that's realistic. It means we hold back the release of the next library version until docs are verified current. If we don't do that, we let people run into defects and hope the average consumer of the learning site is savvy enough with jQuery and the jQuery community to file a bug report themselves... or a community member keeps tabs on things without an easy way to see if anyone else has verified a doc is up to date.

Having a version number on the page gives the reader an assurance of it working with that version, as well as providing a way for the community to know what's out of date.

It might be possible and hopefully not too outlandish to suggest using grunt to unit test code snippets used in those docs.

@rmurphey I like the convention some other docs sites use of putting it onto each page. Some offer drop-downs to switch between minor revisions if there was something that changed (ie, API calls, new ways to do something, etc...)

[rmurphey]

Putting a version number on each article doesn't change the fact that all articles would need to be reviewed for accuracy relative to the current version; it would just mean that, post-release of version x.y+1, there would be a bunch of articles on the site that would be labeled as current for version x.y when most of them would probably be perfectly accurate for version x.y+1.

Major jQuery releases usually go through several pre-releases before the official release. In my opinion, it should be possible for the review of the content to happen during that time; I don't see review delaying the delivery of future releases.

A more complex system that maintains different versions of articles for different releases ... I'd defer to @ajpiano and the folks who maintain the wordpress side of the site to say what would be involved in that.

[rwaldron]

@Incognito I promise you that doc updates will never block releases. (I'm sure @kswedberg is cringing)

[kswedberg]

😓

[Incognito]

@rmurphey

Putting a version number on each article doesn't change the fact that all articles would need to be reviewed for accuracy relative to the current version;

I agree. Version numbers will not give us automated reviewing.

Observations from other docs on the net (ie, MDN, php.net, etc... ):

• There's always something that gets out-of-date. Sometimes years out of date.
• Lacking a clear inventory of what's outdated and what's verified current.
• People using a learning site just go find another one if their site doesn't work
• Defects are reported by a sliver of people who encounter them
• They indicate versions where features were introduced or are stable

Maybe my proposed solution of providing the version in the doc like many other sites isn't innovative enough because jQuery is some special case. So here's the real challenge:

How might we help consumers (authors and readers) of the documentation keep up to date (skills learnt and live content)?

[alimony]

Maybe all articles/pages could be tagged with jQuery version, but only for internal use. As part of grunt, or somewhere else, that tag could be used to easily get a list of "outdated" articles.

The pages would then be reviewed (manually) and retagged with the current stable version, and thus disappear from the outdated list.

This may not reduce any amount of work needed, but it would be an easy way to make sure that someone has gone over the text making sure it is still valid.

[rmurphey]

@Incognito As I said above, I don't really disagree that in theory this is a great idea, and there's no jQuery exceptionalism on my part here, trust me.

In practice, though, any goal other than "do our best to make sure the learn site reflects the current stable release" will increase the overhead of maintaining this site, and depending on the nature of the solution (i.e. dropdowns to select the version of your choosing) may involve some non-trivial engineering time up front as well. I want to be very sure that we understand a) the problem we're trying to solve, b) the size and scope of that problem, and c) what additional responsibilities we'd be asking volunteers to take on as a result.

To that end, I like the suggestion @alimony just made -- put a version number on all current pages (this will still require some amount of upfront review) and use that version internally to manage reviews. @Incognito If you'd like to volunteer to review a release's changelog (at the alpha, beta, and rc stages) and incorporate changes into the content and update the version numbers on individual articles, I'm sure @ajpiano would be grateful.

[Incognito]

@rmurphey I agree it would increase the overhead, but much less than the debt accrued from just winging it as we go.

The last thing I want to see is the site turn into an untrustworthy source because the docs had no accountability to the library. I like the idea of putting version numbers on pages, but it needs to be maintained. To me, maintaining the version on a doc is moot as all the docs need to be maintained. I don't want the job of Czar of the versions -- I'm happy to take on part of that work, but it shouldn't fall onto one person, the same way writing docs isn't be the job of one person, nor does it make sense to version things on all things such as the JavaScript pages.

It sounds like there's consensus that this is a helpful thing to have, but a lot of concern around how much work this will be adding. Is that correct?

[scottgonzalez]

I disagree that the goal of the learn site is to show people only how to use the latest version of jQuery. We should encourage developers to write code in what is currently the best way, but we should be aware of the very large user base that is on older versions of core. It's useful to know which versions an article applies to. For example, an article about .prop() should clearly state that it's for 1.6+. There's already an article about the jQuery UI widget factory. Which version is required for the documented features? How far back can I use the widget factory (both for UI and core)? What about articles about jQuery Mobile or jQuery Color or some popular third party plugin?

Versions are important, and we shouldn't delete an article just because it becomes irrelevant in the current version if it's useful for previous versions. Here's a perfect example: http://blog.nemikor.com/2009/04/08/basic-usage-of-the-jquery-ui-dialog/ This article explains how to use dialogs properly and addresses a very common problem that users run into. We changed how dialogs work in later versions to prevent users from ever running into this problem. However, this article is still useful for a ton of users who are stuck on old versions. If this was on the learn site, I would hope that we wouldn't delete it just because a new version of jQuery UI was released. However, I would also hope that it would be extremely clear to users who come across it that this is no longer relevant if you're using newer jQuery UI.

[Incognito]

Hello friends, two months has passed and there is no clear decision made by anyone... and the only solutions I can read based on the past conversation are to go 'fork off' and create competing docs or maintain a list which its self will just be doomed to the void of useless docs.

Has/Will anything ever come of this discussion? Am I wasting everyone's time?

[scottgonzalez]

I think in general articles shouldn't mention versions at all. In specific cases where versions are important (.attr() vs. .prop() distinction, .live() vs. .delegate() vs. .bind() vs. .on(), xpath selectors, etc.), the article should be clear about the behavior in different versions. This should be treated as a one-off inside the article content, as opposed to a site-wide implementation.

[ajpiano]

I'm with @scottgonzalez, I think this increases a lot of process and overhead for a limited win. We can continue to do our best to keep things current, and note issues on a case by case basis.