Consider use of Gherkin syntax in example implementations of design patterns

[ZoeBijl]

From @karlgroves on September 8, 2015 9:38

This repository's README document discloses contribution guidelines for the ARIA spec. The wiki has a table of Aria Authoring Practices and their status. Neither documents discuss details on requirements for submitting examples. Documenting the requirements (if any) will probably help in getting examples and ensure their quality.

Copied from original issue: w3c/aria#88

[ZoeBijl]

Can you elaborate? There are plans for some code standards:

APG itself: w3c/aria#131
APG examples: w3c/aria#95

Your issue predates both, but is this what you're hinting at? Or should we write a full fledged tutorial on how to contribute?

I'm open to both, and actually think the code examples should be written in a tutorial format (but that is a separate issue entirely).

[ZoeBijl]

From @karlgroves on January 12, 2016 22:30

While coding standards are a good start, I'm looking for something else.

For instance, here's the kind of thing I'd propose if this was my own project:

1. All examples must be a standalone demonstration of a specific concept. This includes all HTML, CSS, and JS without any external dependencies at all.
2. All examples must come with a 'feature' file written in Gherkin syntax that descripts the specific goal of the example and specific user interactions necessary to use the example. Also, where appropriate, the roles, states, and properties that should be exposed to AT are described.
3. All HTML and CSS should be valid.

With some additional effort I'm sure I could make this list even more oppressive, but the general idea is just to codify exactly what you expect so that contributors have some clarity on what they need to do.

[ZoeBijl]

Good points, some comments:

All examples must be a standalone demonstration … without any external dependencies at all.

Do you mean that we should have two documents for each example (one for the actual code and one to document the example)? Or do you dislike all examples sharing a common CSS?

All examples must come with a 'feature' file written in Gherkin syntax

I've seen some talks on Cucumber and automated testing, but don't have any experience with it (this might be a good time to start). I'll look into it and will ask if others have experience and if they can help. Of course, writing the feature file seems easy enough.

All HTML and CSS should be valid.

Couldn't agree more. I have not validated the examples. Have filed an issue: w3c/aria#174

[ZoeBijl]

From @karlgroves on January 12, 2016 22:57

Do you mean that we should have two documents for each example (one for the actual code and one to document the example)? Or do you dislike all examples sharing a common CSS?

I'd be on the fence about having common assets for the repo itself. I can see the possibility of providing a common set of files for convenience.

I guess it depends on the goal. For me, I'd still favor having a completely standalone example that could survive on its own.

[re: Cucumber] Of course, writing the feature file seems easy enough.

I wasn't necessarily proposing the use of Cucumber itself, but Gherkin syntax is a really excellent way to communicate requirements in a very clear and concise way that can be understood by everyone involved.

[mcking65]

Most of this is covered by issues #12 and #19.

The task force is interested in consider Gherkin syntax
for a later version. Changing the title of the issue and setting to a later milestone.