The Document Outline...What's the Deal with that?

FAQ

What would happen if we could flip a switch?

If there were a switch that we could flip tomorrow that would enable the document outline as described to be switched on on the existing web, in some cases, the heading levels communicated on existing websites would change in screen readers.

That's it?

Yes. It could potentially enable development of new affordances which could be better, but that happens in the future, if it happens.

Would this be better for existing content, or worse?

Very hard to say universally since we haven't actually tested "it". In theory, the feeling from the accesibility community is "generally better".

"In Theory?" "It?"

Yes, there are a few problems here... First, there's not exactly an "it" we can flip on. There are a lot of words in a lot of places and a few implementations (polyfills and tools, not browsers) that don't exactly match any of those words.

Wait... why don't they match?

In practice it was difficult and confusing to match the words. There was occasionally some feeling that what it was producing was not entirely great. So, there are a few variant interpretations.

Wow! Why haven't we sorted this out?

Mostly, it's just been really hard to do so far. There is a lot of speculation as to why, but we need to collect more data on that.

We should do that, right?

Collect the data? Yes.

No, but shouldn't we work to switch something very like "it" on?

Maybe. Probably. It's hard to say, we don't even know why it hasn't been done yet... and not everyone agrees on the "it". _We need data, and we need experiments_. It may be the easiest path from a standardization/paperwork standpoint to modify one of the existing sets of words in a spec. But then, effectively we are redefining it again so I'm slightly wary of calling it an existing "it". Hard to say.

What's the challenge?

Well, aside from we don't have a perfect "it" to discuss, first there is a correlary problem that not all change happens simultaneously IRL. What really happens is that for some time there is ragged support.

The second is that each "it" encourages some amount of "new advice" on how to write to really take advantage. If you write code that way then in some cases there is general concensus that in many cases the result will be worse on the unsupporting browsers than if you had done nothing "new" and just kept doing the same old same old.

The third is that having an outline enables new possibilities for anything that uses AT, where "AT" can be thought of as anything that consumes content non-visually (and that is a big/increasing bunch of stuff) that go beyond "some heading levels change".

So, in at least some sense, it's about managing all that.

Ok, so what can we do?

We can work on figuring out what "it" should actually do in practice.

We can speculatively polyfill and test the variations of "it" to produce document outlines such that if you include the polyfill you can go ahead and write "the new way" and everyone will get the same levels and we can use this to discuss/test any "it". The "existing web" will remain unaffected until we have a clear "it" and some browser implements it.

Seems good?

Yes.

Should we do that?

Yes.

Have we?

Kind of, but not really. We have various levels of approximations of existing and new "it" ideas. We need to work better on collecting together existing data and using experimentation to improve the main idea.

So is 'it' a new tag?

In most of the existing specs/words it is not. Some custom elements exist which do some reasonable approximation of a subset, and they use a new tag.

Are you suggesting that 'it' should be a new tag?

The simple answer is: No not necessarily. Personally, I would rather see that if given the choice. I explain in some detail why in my post. I recognize this is my personal choice and it could be wrong. We need some time and data to know, in my opinion.

Can we just polyfill exactly as in the spec, not as a new tag?

Yes! Well, probably. As long as 'it' is polyfillable - and we should! As soon as we figure out which spec and why - or are we going to change the spec to match one of the tools implemntation's approximations because they are more reasonable?

Hmm... Can we try both (as a new tag and not)?

Yes, and that is what I am suggesting is worth doing.

Well... Which one will we standardize?

Who knows? Maybe neither. Maybe both. It's not an argument for or against.... More importantly - does it matter?

Wait, what?

What I mean to say is: Until we have an actual standard, guessing is actually not a great reason to use them. Don't let this hang you up. This is a source of a lot of frustration historically in the Web community - we think we are promised things and then don't come. We believe too much in words that are written down. When one browser implements it, pay attention. When two browsers do, it's more likely. And so on. We're just not there yet and we don't know what's going to happen.

In the meantime: Here is a thing. You can use it if you want because it may be useful. Or don't. Here is another. One may be more paletteable than the other or something. For you, maybe one has really important features. Using h1...h6 oriented polyfill will 'degrade' to a flat bunch of h1s without JS - but a lot of other ARIA isn't going to work well for you since a bunch of it requires JS.

The truth is: We just don't know. What we know is that you have a problem and one of these might help you solve it. If not, how come? If so, well done. That's the job, right? Get shit done. Go spend some time with some "it". Come back and tell us what you think and that will be helpful information.