Refine documentation for DD#337
Conversation
matatk
left a comment
matatk
left a comment
There was a problem hiding this comment.
This is great work, thank you.
I am requesting some changes, but also there are a couple of things (like where content should go) that we ought to address as a group, before we can merge.
| <p>An accessibility auditor is reviewing a portfolio of websites on behalf of a disability rights organization. Each site structures its accessibility statement differently, some link to it from the footer, others from the main navigation, and others only from an internal policy page. The auditor spends considerable time on each site searching for the relevant page before the audit can begin.</p> | ||
| <p>With Discoverable Destinations, a User Agent or assistive technology can immediately locate the <code>accessibility-statement</code> destination on any compliant site and present a direct link to the auditor, regardless of where the site has chosen to place it in its navigation structure.</p> | ||
|
|
||
| <h4 id="use-case-cognitive-navigation">Navigation Support for Users with Cognitive Disabilities</h4> |
There was a problem hiding this comment.
We're primarily doing this work for this use case, so it should come first (and, maybe, be widened a bit).
| <p>A user with a cognitive disability wants to log in to their account on a retail website. The site's primary navigation does not label the login entry point in a way the user recognises, and the page layout makes it difficult to locate. The user's browser extension, which presents a simplified navigation panel, cannot automatically locate the login page because no standard signposting exists.</p> | ||
| <p>With Discoverable Destinations, the browser extension can read the <code>log-in</code> destination from the page's <code><head></code> and present a clearly labelled button in its simplified interface, giving the user a direct and reliable path to the page they need.</p> | ||
|
|
||
| <h4 id="use-case-ai-agent">AI Agent Assistance</h4> |
There was a problem hiding this comment.
This actually to me seems like it's describing another accessibility use case. I would put this as a sub-section of the accessibility use cases, but I wouldn't reference AI agents here. This would apply to existing speech recognition based navigation technology, if it were updated to support it.
For the AI agents use case, I would say something a bit more general, like an agent that's navigating a site on behalf of a user (headlessly).
| <p>A user with motor impairments uses an AI-powered assistive agent to help navigate websites and complete common tasks. The user asks the agent to "find the help page for my internet provider." Without semantic signposting, the agent must attempt to locate the help page by guessing at URL structures or parsing navigation HTML, which is brittle and may fail when the site is updated.</p> | ||
| <p>With Discoverable Destinations, the agent can query the <code>help</code> destination directly from the site's page headers, retrieve the correct URL in a single step, and navigate the user there reliably, regardless of how the site has structured its navigation menus.</p> | ||
|
|
||
| <h4 id="use-case-password-change">Password Change Assistance</h4> |
There was a problem hiding this comment.
I don't think we can use this, as that spec uses well-known URIs. I think it adds too much confusion.
| @@ -228,27 +244,40 @@ <h3 id="demarcating-destination-content">Demarcating destination content</h3> | |||
| </ul> | |||
|
|
|||
| <h2 id="open-questions">Open Questions</h2> | |||
There was a problem hiding this comment.
A lot, if not all, of this stuff should really just be in the explainer (that's my fault; I moved it across to here). The spec is meant to be definitive, confident, and contemporary.
That's because it needs to be very clear to someone reading it how to implement it.
In our case, this is more of a best practices document, but we still need to be clear and confident.
Whilst we're at the early stages of development, maybe we could soften this, but as we are intending to have a first round of implementations before TPAC, we should probably move some of this back to the explainer.
| <p><strong>The Task Force has agreed to adopt the <code><link></code> element approach for the first iteration of this specification.</strong> This decision reflects that the approach has a low entry barrier, as it builds on existing, well-understood HTML mechanisms that content authors and User Agents already support, requires no new infrastructure, and can be incrementally adopted. The per-page repetition, while an authoring overhead, can be managed in practice through CMS templates.</p> | ||
| <p>The following questions remain open for future iterations:</p> | ||
| <ul> | ||
| <li><p>Should there be a single canonical discovery endpoint, such as a well-known URI, that a User Agent can consult once per origin rather than reading destinations from each individual page? This would reduce per-page overhead but would require an additional HTTP request on first visit to a site.</p></li> |
There was a problem hiding this comment.
We have been advised against the use of well-known URIs in the strongest possible way, so I don't think we should include mention of that here.
We were also advised against linksets (as they, too, add complexity to the UA) though I am personally sympathetic to their use - I think the point is we'll have to demonstrate that they are really necessary, by having lots of people use the best practice in its current (<link>) form.
Also, if we want to allow the use of linksets in future, we'll have to check that any proposed solution to the 'type of content' problem above will be expressable in a linkset.
| <li><p>Extending the <code>rel</code> value vocabulary to include more specific destination subtypes (for example, <code>help-human</code> or <code>help-chat</code>). This approach is specific and directly discoverable by User Agents, but risks becoming unwieldy as the number of content kinds grows.</p></li> | ||
| <li><p>Using an additional attribute or a companion <code><meta></code> element alongside the <code><link></code> element to annotate the kind of support offered, keeping the destination identifier stable.</p></li> | ||
| <li><p>Deferring this concern to the destination page itself, where structured data markup could describe the available support types. This places the burden on page authors and requires User Agents to fetch and parse the destination page before presenting options to the user.</p></li> | ||
| </ul> |
There was a problem hiding this comment.
Another option: don't address it as part of this spec (we should consider that option).
| <li><p><strong>Overriding destinations is straightforward.</strong> A sub-site page that declares a different <code>contact</code> destination than the root site will naturally present the sub-site's destination to the User Agent, since the User Agent always uses the current page's declarations.</p></li> | ||
| <li><p><strong>No additional authoring mechanism is needed.</strong> Content authors control sub-site scoping by controlling which <code><link></code> elements appear on each set of pages, typically managed through their CMS templates.</p></li> | ||
| </ul> | ||
| <p>The Task Force considers sub-site demarcation to be resolved by the per-page <code><link></code> approach.</p> |
There was a problem hiding this comment.
There are some good suggestions here - thanks!
Though we have not made a decision yet on how to approach sub sites (this text seems to say that we have).
| @@ -296,18 +325,18 @@ <h3 id="integration-patterns">Integration Patterns</h3> | |||
|
|
|||
| <section> | |||
| <h2>Requesting Additional Destination Types</h2> | |||
There was a problem hiding this comment.
Your additions in this section are great! Very clear; thank you.
| <h3 id="security-considerations">Security Considerations</h3> | ||
| <p>All navigation uses standard HTTP and HTTPS requests subject to normal browser security policies. Destinations are typically within the same origin, which reduces cross origin security concerns. Content authors are responsible for ensuring that the <code>href</code> values in their <code><link></code> elements point to legitimate, secure pages.</p> | ||
| <p>All navigation uses standard HTTP and HTTPS requests subject to normal browser security policies. Destinations are typically within the same origin, which reduces cross-origin security concerns. Content authors are responsible for ensuring that the <code>href</code> values in their <code><link></code> elements point to legitimate, secure pages under their control.</p> | ||
| <p>User Agents and extensions that implement a discoverable destination interface should validate that destination URLs share the same origin as the page from which they were discovered. Where a cross-origin destination URL is present, User Agents should present the full URL to the user before navigating, to support informed decision-making.</p> |
There was a problem hiding this comment.
Nice!
We have a security expert on our team here, so I will ask him to review this once we've merged it and are getting closer to 'final' draft.
|
|
||
| * Providing additional context or guidance based on the destination type. | ||
|
|
||
| ## Open Questions |
There was a problem hiding this comment.
Thanks for adding the content to the explainer. I think most of this fits better here. We should aim to have content only in one place, and link between the two (mainly from the explainer to the spec) when necessary.
2 participants
No description provided.