RE: Selecting evaluation tools - Final (?) version

Thanks Eric for the suggestions.  I’m still unsure as to how to proceed as I still remember Shawn stating that the document was being updated to specifically align with the tools list.  Before I move forward in a specific direction it would help immensely to get feedback from the planning team.

Thanks,
Laura

From: Eric Eggert [mailto:ee@w3.org]
Sent: Monday, November 20, 2017 10:57 AM
To: Shadi Abou-Zahra
Cc: Keen, Laura; Nic Steenhout; EO Editors
Subject: Re: Selecting evaluation tools - Final (?) version


I think the document wants to do two things at once and that is what makes it and the discussion around it hard to understand:

  1.  Describe what is important when selecting any tool.

  1.  Saying “And you can filter by this category in the Tools List interface.”

I wonder if we could write the document as if the tools list wasn’t there (explaining why several of the filters are important and what they do) and then say “you can filter by x in the tools list“. Or we could have a box that says “Tools list”, “You can filter our list of n available tools by many of the categories below.” (We could mark those categories somehow.)

I think the following highlights Shadi’s concerns pretty well:

Type of Tool
Lists the platform and type of tools that are available, e.g. authoring tool or browser plugin, command line, desktop or mobile application.

This would be an adequate description for an information for the tools list filters, but it does not say a lot if you want general information on a tool, while the following is better at that (I hope at least as a very bad example):

Type of Tool
Select a tool that works on the platform you are using, for example sometimes you want to evaluate when writing in an authoring tool (CMS) or use the command line.

I hope this helps to clarify the different views on the document. I’m happy to help where I can to move things forward.

Best, Eric

On 20 Nov 2017, at 0:01, Shadi Abou-Zahra wrote:

Hi Laura,

First of all, I note several good changes! Many thanks for considering my suggestions. Yet it seems we still have differing opinions on some aspects, and I'm not sure how the EOWG process addresses such impasses.


On 19/11/2017 22:08, Keen, Laura wrote:

Shadi,

Nic and I are both stuck with what you're asking us to do with these last comments. I still go back to Shawn's initial direction to me about what this document is supposed to do. The update I was told was to align with the tools list.

In my opinion we are not deviating from Shawn's initial direction.

I believe this is the latest requirements document?
- https://lists.w3.org/Archives/Public/public-eo-plan/2017JulSep/0023


It lists three objectives in the "Purpose" section:
[[
● The purpose for the Selecting Web Accessibility Evaluation Tools document is to provide our audience with information to consider when selecting a tool to evaluate web sites for accessibility.
● Explain the detailed info categories/filters in the Tools List.
● Warn what tools can't do (e.g., some things need manual, most need knowledgeable human).
]]

I feel we are leaning more towards the second item and not addressing the first as well as we should. That is, provide information on tools.

What you're suggesting is that's not at all what it should be about. Also I'm not sure what you mean by describing the actual feature of a tool. If we were to describe actual features of specific tools this would be a very long list.

That is not what I'm suggesting at all, sorry if I'm still unclear. My concern is when this document implicitly refers back to the tools list, making it difficult to use without knowing the tools list first. You addressed most points but here are a few more examples to illustrate:

Current text: "Type of Tool Lists the platform and type of tools that are available, e.g. authoring tool or browser plugin, command line, desktop or mobile application."

Issue: to me, this does not really explain the types of tools there are to someone who is new to tools and trying to learn about them. In fact, "type of tools: lists the [...] type of tools" seems kind of redundant and less informative. Also, when it says "lists", it is referring back to the tools list, which in my view creates an unnecessary dependency.

Suggested text (from my pull request): "Evaluation tools can be plugins (extensions) for authoring tools and web browsers, command line tools, desktop or mobile applications, and online services. Diffent tools may be combined, depending on your design and development process."

I'm not at all stuck on this particular wording, but my intent was to make this a more stand-alone description of "type of tool".


Similar issue with "Supported Formats":

Current text: "Supported Formats Lists the format the tool can test, e.g. HTML, CSS, PDF, etc."

Issue: while "supported formats" is more self-evident to many readers, the description seems less useful to me. Also the same issue with the implicit reference back to the tools list, which seems unnecessary.

Suggested text (from my pull request): "Most evaluation tools check the accessibility of HTML content. Some also support other web technologies, such as WAI-ARIA, CSS, SVG, and PDF."

Again, not stuck on this wording at all but strong preference to giving the author a little more "feel" for the feature - what is this about?


Final example:

Heading "Main Features" and the directly following sentence "You may use the following features to reduce the number of evaluation tools listed."

Issue: in my view, this is not an exhaustive list of the *main* features when selecting tools. They just happened to be the features that we have for filtering in the tools list. There are many other important features that we do not consider in our tools list, such as performance aspects. Also the sentence after this heading does not explain this. Instead, it refers to the tools list again, which is not very clear (listed where?).

Suggestion: move the sentence before the heading to after the heading, so that the reference to the tools list is made explicitly and clearer: "The following features describe tools found on the Web Accessibility Evaluation Tools List. These can be used as filters to reduce the number of tools shown." This may help some, but I still strongly recommend to find another heading that is independent of the tools list.

I do think we need help from the planning team to resolve the direction of this section of the document.

Yes, I agree. We seem to have differing opinions and need to resolve it.

Many thanks for all your efforts and improvements!

Regards,
Shadi

Thanks,
Laura



-----Original Message-----
From: Shadi Abou-Zahra [mailto:shadi@w3.org]
Sent: Tuesday, November 14, 2017 10:09 AM
To: Nic Steenhout
Cc: Keen, Laura; EO Editors
Subject: Re: Selecting evaluation tools - Final (?) version

On 14/11/2017 15:59, Nic Steenhout wrote:

Thanks Shadi,

Regarding #1, I'll adjust that. We need a heading, but your point does
make sense.

Regarding #3, it's in the EO style guide

Regarding #4, I'll move it up. As I wasn't able to simply merge your
pull request, I had to go through the file manually and obviously missed it.

Regarding #2, I'm honestly not seeing it, and I'm not sure how it is
the same underlying issue. But I'll have a look.

To me, several descriptions require me to first look at and understand the tools list before I can understand the descriptions. Usually these start with "lists ..." to describe the functionality of the tools list rather than the actual feature of a tool.

I'll update #1, and #4 momentarily.

Let me know if you need more input on #2 after you've taken a look.

Best,
Shadi

Nic

On Tue, Nov 14, 2017 at 9:11 AM, Shadi Abou-Zahra <shadi@w3.org
<mailto:shadi@w3.org>> wrote:

Hi Nic,

I only had time to do a quick skim, but many thanks for addressing
many of my concerns! Just a few things that caught my attention, though:

- I still don't really like the heading "Features You Can Use as a
Filter". It just does not make sense to me on this page, if I'm not
aware of the tools list. It takes quite some mind work (eg read the
*prior* paragraph) to understand the context.

- I find the tone and approach of the descriptions rather
inconsistent and confusing. Often you are describing the
functionality of the tools list rather than the actual tool feature
itself.

- Not sure about use of "e.g." and "etc.". I don't like that style
(personal opinion), but don't know if it is covered in the EO guide.

- "Accessibility Information" is actually a feature that you can
sort by. I had moved it up. Not sure if you disagree or just missed it.


Are these comments helpful for you, or do you prefer that I raise
them as issues or put them in another pull request?

Best,
  Shadi



On 13/11/2017 21:05, Nic Steenhout wrote:

Hello Shadi,

Laura and I have, we think, finalized and incorporated the
changes you suggested to the Selecting evaluation tools page.

https://github.com/w3c/wai-selecting-eval-tools/blob/master/index.md

<https://github.com/w3c/wai-selecting-eval-tools/blob/master/index.md>

I had to rewrite the page manually as I was not able to merge
only parts of your pull request.

We both like how the page is looking at the moment.

Could you have a look and if things are good on your front,
we'll be able to initiate a request for review from the whole
group this Friday!

Thank you

Nic


--
Shadi Abou-Zahra - http://www.w3.org/People/shadi/

<http://www.w3.org/People/shadi/>
Accessibility Strategy and Technology Specialist
Web Accessibility Initiative (WAI)
World Wide Web Consortium (W3C)

--
Shadi Abou-Zahra - http://www.w3.org/People/shadi/ Accessibility Strategy and Technology Specialist Web Accessibility Initiative (WAI) World Wide Web Consortium (W3C)

--
Shadi Abou-Zahra - http://www.w3.org/People/shadi/

Accessibility Strategy and Technology Specialist
Web Accessibility Initiative (WAI)
World Wide Web Consortium (W3C)

--

Eric Eggert
Web Accessibility Specialist
Web Accessibility Initiative (WAI) at World Wide Web Consortium (W3C)