Documentation does not make clear how certain APIs were changed or expanded in v2.0 or other updates

dvgp4

The first page of the manual states:

The documentation here is the latest release version of DataTables. However, most concepts apply for older versions as well and the documentation is marked to indicate when an API was introduced.

However, this is not sufficient for someone who is trying to figure out what options are available and how they can be used in an older DataTables version (specifically in my case, v1.13). For instance, I want to set an initial sort order, ideally by column name. So I look up "sort" or "order" on https://datatables.net/reference/option/ and find the docs for order: https://datatables.net/reference/option/order

At the top of this page it states "Since: DataTables 1.10", so I presume I can rely on this documentation for v1.13. I see I can pass an object with name/dir parameters to sort by a certain named column--exactly what I want. Oops! this doesn't work. Some troubleshooting later, I find that this particular input for order was only introduced in v2.0, so I can't actually use it in v1.13, but this wasn't indicated anywhere on the page.

One solution would be to tag subsections of pages that document new functionality with the version that introduced them, rather than just the whole page.

Another solution would be to preserve a documentation site for DataTables prior to the 2.0 release, which (as the number implies) brought a host of major additions and changes. It looks like this was done with the similarly large 1.9->1.10 update.

allan

I true to add a since x.y.z note in the documentation if a particular option has been expanded. I missed it for that one - I've committed a change that I'll deploy to the site soon. The moment.js docs were part of my inspiration for this.

I've wondered about having a site for the old documentation, and did actually do that for v1 prior to v1.10 (as you note), but it increases the support and maintenance burden, which I just don't have the bandwidth to handle - I can barely keep up with support as a full time job, even with the amazing help of the community volunteers in this forum. DataTables 1.x is no longer supported. I'm not ruling it out and perhaps some future iteration of this site will make it easier to deploy documentation like that, but I want to encourage folks to upgrade - DT2 is almost fully backwards compatible - it isn't completely different.

Allan