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.
| @@ -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.
There was a problem hiding this comment.
As discussed on the call, I propose we merge this PR and proceed in two steps:
- You can then do a clean-up pass to ensure this specification content aligns with W3C editorial guidelines.
- Once that is complete, I will create a follow-up PR to update the explainer , replacing duplicated content with links to the relevant sections of the specification, so that we maintain a single source of truth.
| <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.
There was a problem hiding this comment.
-
I agree we should not include well-known URIs or Linksets as options in the specification itself, given the strong guidance we have received. However, I think the alternatives we evaluated should be documented somewhere for transparency and to avoid revisiting the same ground in future. The explainer documents would be a natural home for this. Basically, recording what was considered, the rationale for not pursuing each option at this stage, and the conditions under which they might be revisited.
-
Even without naming specific alternatives, I believe the specification should include a brief note indicating that the Task Force may explore complementary or alternative discovery mechanisms in future iterations, as implementation experience demonstrate the need. This sets appropriate expectations for readers without committing to any particular direction.
-
Could we take this up on the next call to align on the appropriate level of detail and tone?
There was a problem hiding this comment.
On this, there isn't a solution yet, but it's acknowledged that there's a gap between well-known URIs and more organic service discovery.
The TAG intends to talk about this at its upcoming face-to-face meeting - here are some pointers to what we'll be discussing: w3ctag/design-reviews#1243
| <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).
There was a problem hiding this comment.
I think it's important to retain this section either here or in explainer, even if we ultimately decide not to address it within this specification. The reason is the problem is real and well-documented (users with cognitive disabilities genuinely need to know whether they'll reach a human, a chatbot, or an email form), and readers of the specification will naturally ask about it.
By acknowledging the problem and listing the options, we demonstrate that the Task Force has considered it and made a deliberate choice, rather than having overlooked it.
That said, I'm happy to add "not addressing this within the scope of this specification" as a listed option alongside the others, with a note on the trade-off (simplicity and focus for this iteration, at the cost of leaving a known user need unresolved). Would that work?
|
|
||
| * 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.
There was a problem hiding this comment.
As discussed on the call, I propose we merge this PR and proceed in two steps:
- You can then do a clean-up pass to ensure this specification content aligns with W3C editorial guidelines.
- Once that is complete, I will create a follow-up PR to update the explainer , replacing duplicated content with links to the relevant sections of the specification, so that we maintain a single source of truth.
matatk
left a comment
matatk
left a comment
There was a problem hiding this comment.
This is great work, thank you @abhina-kumar.
As we've discussed, we need to avoid repetition across the (intended) Note and the Explainer. We can do this in future PRs (I'm happy to help with the editing there).
| <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.
On this, there isn't a solution yet, but it's acknowledged that there's a gap between well-known URIs and more organic service discovery.
The TAG intends to talk about this at its upcoming face-to-face meeting - here are some pointers to what we'll be discussing: w3ctag/design-reviews#1243
As discussed in previous calls. I would like you to clean-up the (intended) Note. Post which I will clean up the explainer by creating hyper links. |
SHA: 4fbcb33 Reason: push, by abhina-kumar Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
SHA: 4fbcb33 Reason: push, by abhina-kumar Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
SHA: 4fbcb33 Reason: push, by abhina-kumar Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
SHA: 4fbcb33 Reason: push, by abhina-kumar Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
SHA: 4fbcb33 Reason: push, by abhina-kumar Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2 participants
No description provided.