EN 301 549: 5.2 documented accessibility features

5.2 is only applicable if an accessibility feature is documented (as a pre-clause) i.e. a contrast switcher or font-size enhancer.

What does it mean "documented", a contrast switcher i.e. will be usually not be documented ...

changed the description

This wording has been a cause of confusion for others. The requirements are primarily aimed at what webpage/software developers are required to do and is meant to refer to features that are described in documentation made available by platform providers to developers, including API specifications. This part of EN 301 549 is already under active consideration, and the wording will change (see issue #256 (closed)). Hopefully, the ambiguity regarding such language can be removed in the next version of EN 301 549. We will almost certainly need to define what is meant by "documented" more thoroughly.

thx - would be a huge improvement what is meant by "documented". We have to wait.

Proposed definition

documented platform accessibility service

a service provided by the platform that is documented for public use by accessibility applications and utilities created by third parties.

Note 1: Such services are provided for use by assistive technologies to keep them from attaching themselves in ad-hoc fashion to platforms and are generally very stable over time although there have been examples in early days where they were replaced by a new paradigm for AT connection.

Note 2: These services are also often used by non-accessibility software and testing software.

A good initial definition, but I think we could/should lose the historical observation "although there have been examples in early days where they were replaced by a new paradigm for AT connection" at the end of the first note.

fine with that. do you mean just drop the end of note 1? like this?

Proposed definition

documented platform accessibility service

a service provided by the platform that is documented for public use by accessibility applications and utilities created by third parties.

Note 1: Such services are provided for use by assistive technologies to keep them from attaching themselves in ad-hoc fashion to platforms.

Note 2: These services are also often used by non-accessibility software and testing software.

added Definition label

mentioned in issue #257 (closed)

added Proposed for approval label

marked this issue as related to #101 (closed)

mentioned in issue #101 (closed)

In clauses 11.5.2.3 and 11.5.2.4 we have a NOTE that says:

The term "documented platform accessibility services" refers to the set of services provided by the platform according to clauses 11.5.2.1 and 11.5.2.2

This is really a definition, to ensure that we are using the term in a consistent way throughout the document I believe that we should merge these notes into the definition (and then link to the definition wherever we use the term), the revised rather lengthy but important definition would read:

First proposed definition

documented platform accessibility service

a service provided by the platform, according to clauses 11.5.2.1 and 11.5.2.2 of the present document, that is documented for public use by accessibility applications and utilities created by third parties.

Note 1: Such services are provided for use by assistive technologies to keep them from attaching themselves in ad-hoc fashion to platforms.

Note 2: These services are also often used by non-accessibility software and testing software.

As 11.5.2.1 and 11.5.2.2 use the term "documented platform services" it would be good to include another similar definition for these:

Second proposed definition

documented platform service

a service provided by the platform that is documented for public use by accessibility applications and utilities created by third parties.

Note: Such services are provided to keep software from attaching itself in ad-hoc fashion to platforms.

As well as "documented platform accessibility services", the term "documented accessiblity features" is used in several paces. This also needs a clear definition. Here is a proposal which hopefully captures the intent of this term:

Third proposed definition

documented accessibility feature

a feature offered to end-users that can enhance accessibility and that is provided to users in the user interface and in documented in instructional material made available to users.

Note: Such features are often presented to users as accessibility user preference settings.

We could attempt to define "documented" as it also occurs in other places in the document with slightly broader meanings e.g. "documented accessibility feature" might imply that this is documented somewhere else than in the platform documentation (e.g. documented in a Readme.md file in a GitHub repository for a software library).

Fourth proposed definition

documented

information about a service or feature that is publicly available to those that might make use of the service or feature.

Example: The information might be provided in a GitHub Readme.md file for software developers whereas the information intended for users would be documented in product documentation and help systems for end-users,

This all look good but should all have the phrase "by the platform author"

Hooks that are documented in an "how to hack Windows" would be documented in public for people to attach things to the OS -- but should not count. It should only apply to things "documented by the manufacturer/platform provider/platform author (or some other such name for the platform creator)"

A few comments here:

1. I think it is very good to have definitions for most of these terms. Especially now, since the latest drafted version of clause 11.7 includes "platform documented accessibility features". There's a relevant recent comment by @redux at #23 (comment 18513)
2. We may want to include more related terms, see #257 (closed) :

• "documented accessibility features" (mentioned in clause 5.2 and 11.6.2)
• "platform accessibility features" (mentioned in 11.6.1)
• "accessibility and compatibility features" (mentioned in 12.1.1, 12.2.2)
• "accessibility features of software" (mentioned in 11.1.3.1.1 and 11.4.1.2.1 )

3. However, I think it may be problematic to have a definition for such a generic word as "documented". It is possible that this word will be used for other things in other places in the specification (if not now then maybe in the future, and editors may be unaware that the word "document" in fact has been given a specific definition within this document).
4. Does "for public use" have to appear in the definitions? Does it refer to the public availability of the documentation or of the service? The latter, I think, but this could be made more clear. Especially as, in the context of api:s (and accessibility services are usually api:s), the term "public" can have a very specific technical meaning.
5. The terms "accessibility applications" and "non-accessibility software" appear in the proposed definitions. I am not sure those terms are defined anywhere.

Revised definitions:

First proposed definition

documented platform accessibility service

a subset of the platform's application programming interface (API) that support interoperability between a user interface running on the platform software and assistive technology

Note 1: They allow application developers to create software that is compatible with assistive technologies.

Note 2: These services are also often used by non-accessibility software and testing software.

As 11.5.2.1 and 11.5.2.2 use the term "documented platform services" it would be good to include another similar definition for these:

Second proposed definition

documented platform service

a service provided by the platform that is documented by the platform author for public use by accessibility applications and utilities created by third parties.

Note: Such services are provided to keep software from attaching itself in ad-hoc fashion to platforms.

As well as "documented platform accessibility services", the term "documented accessiblity features" is used in several paces. This also needs a clear definition. Here is a proposal which hopefully captures the intent of this term:

Third proposed definition

documented accessibility feature

a feature offered to end-users that can enhance accessibility and that is provided to users by the platform author in the user interface and is documented in instructional material made available to users.

Note: Such features are often presented to users as accessibility user preference settings.

To avoid complications arising from similar terms the text of clause 12.1.1 will be changed to:

Where ICT includes product documentation, whether provided separately or integrated within the ICT,
the documentation shall list and explain how to use the accessibility features of the ICT and its compatibility features with assistive technology.

removed Proposed for approval label

added Included in EN label

These definitions and the text change at the end of the above issue were agreed at the 29th January 2025 meeting of STF614 and have been incorporated into the latest editor's draft.

closed