Language tabs lack accessibility

[UltimateGeek]

The language tabs have the following deficiencies:

1. There are not obvious
   • Consequence: new users may not even notice that they can switch between the tabs to see different language support.
2. They don't have the names of the languages: neither by default (only an image is shown representing the language), nor by tooltip (when hovering over the tab, it does not show you the name of the language)
   • Consequence: users unfamiliar with the icon representations don't know what language the documentation is on

[mattwynne]

You make some excellent points @UltimateGeek

It sounds like you have expertise in this area. Is there any chance you would be willing to help us fix these issues? We can give you as much support as you need.

[aslakhellesoy]

We've discussed this previously in the open source weekly meetings.

I think we should abandon the whole language tab idea and move more of the platform-specific documentation to plain old GitHub Markdown files in the respective Cucumber-* repositories. We're doing this already here: https://github.com/cucumber/cucumber-js#documentation

The reason I want to abandon it is that it's too difficult to write documentation this way. There are lots of if statements in the Markdown code to display/hide contents for various languages.

• Some sections don't have language specific content and just show up blank
• Some content is so platform-specific that we couldn't possibly have language-specific content
• These if statements are cumbersome to edit
• We cannot easily version the docs (but we can if we do like Cucumber.js does)
• It's easier for contributors to update docs when they are in the same repo as the code

We can keep high-level platform-agnostic content where it is now though.

• We cannot version the docs

[aslakhellesoy]

/cc @davidjgoss @aurelien-reeves @mpkorstanje @charlierudolph

[mattwynne]

IMO it's useful to have the option to provide language specific docs sometimes, so I wouldn't want to throw the baby out with the bathwater.

I agree that some of the pages have got a bit ridiculous with their if statements. I'm ambivalent about whether moving those docs off the /docs site is a good idea. It might be simpler to just copy/paste those pages for specific languages and suffer a bit of duplication in the prose. We know from past efforts that any significant change to the docs site is a heavyweight undertaking and I'm not sure this is a priority right now.

[mattwynne]

I wonder if we should create a separate ticket for your proposal @aslakhellesoy so we don't derail from the original point of this issue. Obviously we need to resolve your point too, but they're separate threads I think.

[aurelien-reeves]

Done.
So this ticket is now dedicated to improving the language tabs: adding proper text and/or title on it for example.

To discuss more general improvements of the doc, please go in #633

[davidjgoss]

I ran up a small change just to add title attrs, meaning (for sighted users) you can at least hover and get the tooltip:

• add title attr on each language tab link #632
• https://deploy-preview-632--cucumber.netlify.app/

However I had a quick play with VoiceOver and the tabs don't seem to be very accessible in general (with or without that change) - needs a bit more looking at I think.