Specify that .data and .attr can't be mixed

I found out the hard way that you can't mix usage of .data and .attr.

The .data documentation clearly states that it doesn't change the DOM upon setting a value.

However, the .attr documentation talks at length about the difference between it and prop, but does not state that it doesn't change the dataset of the DOM node, as demonstrated here: https://codepen.io/cosmo0/pen/YzKVBPp?editors=0011

So your code has to be very strict about using either .data or .attr, because mixing both can result in unexpected behavior, at least when you don't know how jQuery works.

I understand it's by-design, but maybe a warning in the .attr documentation (and/or the .data?) would help people to not fall for this trap?

Start with the .attr and .data documentation and review the linked CodePen example to confirm the behavior described. Done means the relevant documentation clearly warns that mixing .data and .attr can produce unexpected results because they do not update the same DOM state.