The spec should include feature explanations in plain language (Moved from Bugzilla)

[johnfoliot]

MOVED FROM BUGZILLA: https://www.w3.org/Bugs/Public/show_bug.cgi?id=28510

Reply: no change, we rely on external documents to provide an
authoring guide.

APA Response: There are actually 2 responses here.

The first is related to an on-going request from APA that W3C Technical
Recommendations also include, when and where necessary, prose summaries in
"plain english" that explain features and functions of the various parts
of any given spec. The intent here is to explain what is happening with the
technology in lay terms, rather than explain how to create content using
the technology. (i.e.: don't just show an API [sic], explain it.) This
remains an important request from APA, but is not a blocking issue.

The second response is related to Authoring Guidance documents (referenced
in your reply). Following up on the Bug Tracker, it shows a link to an
authoring guidance document (
https://docs.webplatform.org/wiki/concepts/VTT_Captioning), yet that URL
returns a 404 today.

• Has this document been relocated elsewhere? If yes, can we please have
  the reference URL. If no, does the WG plan on updating/recreating this
  document? (This also ties-back to Item Remove the static copy of the spec. #1)

• The current WebVTT Working Draft (https://www.w3.org/TR/webvtt1)
  currently has 'editorial guidance' as part of the normative specification
  addressing privacy and security, and APA's request is that editorial
  guidance for accessibility considerations also be provided in the same
  fashion (i.e. directly in the Rec, as opposed to linking out.)

APA would be pleased to assist in the review of any authoring guidance that
emerges from the WebVTT WG.

[dwsinger]

Yes, since that response, Web Platform Docs has gone away, but before it did, we rescued the authoring guide and put it on the Wiki at https://www.w3.org/wiki/VTT_Concepts

We feel that the spec. already has rather a lot of general background text, and it's not clear that adding more would improve readability. We'd be happy to consider specific suggestions and requests, however, and my preference is that we not delay more and do that during the CR period.

[silviapfeiffer]

@johnfoliot could you check the current editor draft at https://w3c.github.io/webvtt/ - it has many more descriptions in the introduction section and explains the data model better.

Could I ask what kind of accessibility guidance you'd like to see added? Could you provide some wording?