I think this is a great question, and thank you for caring about the experience of an assistive technology user. The short answer to your question is do nothing.
The reason for this is screen readers have a few features to help out with exactly this sort of thing. First are screen reader heuristics, which analyze content and announce it based on what it expects the phrase is. Second are user-defined pronunciations, for things that a user would explicitly want spoken in a certain way. Third is verbosity settings, which control the level of chatter the screen reader has.
The reason you don't want to adjust announcements is you might override a user's settings, and therefore expectations for how this content is announced. If there is confusion over the announcement, there are methods for a screen reader user to go over the content in a more granular way to figure out what is going on.
As for ARIA and the title attribute from previous comments, three things:
The first rule of ARIA dictates not using it when there are other methods. In this case, the text itself is sufficient.
The title attribute should not be applied to an abbr element. Here's a good explainer by someone who know their stuff.
The answer to the question is less "here's how you do it" and more "you don't need to do it," and by not doing it you're actually providing a better experience for your users!
Are there still times when manually adding your own definitions can help? (E.g. in the case of the JSON example I provided. Even though that's one of many examples that could be thought of, that involve making the SR confused.)
There might be some extreme cases, but the JSON example is another case of not needing to do anything. There's enough context in the native semantics of the elements you're using to display the code example, as well as the surrounding content.
Less is more definitely feels weird at first, but it's important to remember by not over-describing you're making things better. Here's another good post on this topic.
I think this is a great question, and thank you for caring about the experience of an assistive technology user. The short answer to your question is do nothing.
The reason for this is screen readers have a few features to help out with exactly this sort of thing. First are screen reader heuristics, which analyze content and announce it based on what it expects the phrase is. Second are user-defined pronunciations, for things that a user would explicitly want spoken in a certain way. Third is verbosity settings, which control the level of chatter the screen reader has.
The reason you don't want to adjust announcements is you might override a user's settings, and therefore expectations for how this content is announced. If there is confusion over the announcement, there are methods for a screen reader user to go over the content in a more granular way to figure out what is going on.
As for ARIA and the
titleattribute from previous comments, three things:titleattribute should not be applied to anabbrelement. Here's a good explainer by someone who know their stuff.role="text"isn't well supported, and also wouldn't be applicable in its use here. Here is another good post to reference.The answer to the question is less "here's how you do it" and more "you don't need to do it," and by not doing it you're actually providing a better experience for your users!
Are there still times when manually adding your own definitions can help? (E.g. in the case of the JSON example I provided. Even though that's one of many examples that could be thought of, that involve making the SR confused.)
There might be some extreme cases, but the JSON example is another case of not needing to do anything. There's enough context in the native semantics of the elements you're using to display the code example, as well as the surrounding content.
Less is more definitely feels weird at first, but it's important to remember by not over-describing you're making things better. Here's another good post on this topic.
Alright.
Though, how do if I know I'm using the right elements for screenreaders?