> If HTML5 data-* attributes change during program execution, use jQuery's .attr() method to get the current values.

I'm not sure why anyone would want to use an attribute for storage, but this is good info. I for one love data-* attributes. It's better than the days of trying to pack info into the id or rel attributes.

Why not just add arbitrary attributes to HTML nodes (before the data- attributes were standardized)?

Is there some reason not to do that besides 'it would fail a validator test'?

The attributes you decide to use now may wind up in the HTML spec some day. If that were to happen, your site may break.

...I hear that a bit when this question comes up. Personally, I think the site would be due for an update by then anyway.

> Updating DOM attributes each time data was changed would slow things down for no good reason.

TLDR: Only use HTML5 data-* attributes server side. Just use .data() to manipulate data in the client.

Yeah, that's exactly the scenario we were expecting: HTML markup would specify some data that would be used to initialize jQuery's data object.

Wow, so agreed, accessing the DOM each time data() is called would be slower. There is a bigger problem though, they have created a situation where a person would reasonably think that it works in a certain way, but it doesn't work that way at all.

This is the first place I have seen this behavior documented. Luckily, I have not ran into problems because of the weird behavior, but this could clearly cause a developer some confusion.

If by "they" you mean the W3C then yes I agree. :)

The reason I wrote the post was because people see the `.data()` API in jQuery, which existed before HTML5, and think it has something to do with `data-` attributes. Indeed, we made it import them, but there isn't a good reason to keep them "in sync" -- and many reasons not to do that.

I think all of behavior has been documented for some time, it's just spread across two or three different pages at http://api.jquery.com. Also, the blog post is emphasized to draw the attention of people who are trying to misuse it to manipulate HTML5 `data-` attributes.

When I say they, I mean the jQuery team, or whomever made the decisions to make the data api work that way. Clearly if someone was carefull in reading how the data api interacted with the data-* attributes they would see what was going on. The blog post is helpful in pointing out what jQuery actually does. I am just not sure in a cursory look at the api it would click in someones mind that it worked like that.

For somebody like me that doesn't use JavaScript and jQuery on daily basis it's quite a mess to remember all those rules.

I can see benefit of using 'data-*' attributes though.

For the most part I think the works the way someone would expect and want. So if you don't think about it too much, it'll probably do that right thing for you.

I agree. All I as trying to say it's not that intuitive.