Process design for Open UI

[boazsender]

On the CSS-WG/Open-UI joint call today, it came up that we should codify the Open UI working-mode/process into a process document. This issue is to discuss what should be in that process doc and to create a draft of that process doc.

Some initial things we should add:

• scope (e.g. controls and component)
• research process
• accessibility, privacy, and security review
• where to discuss use cases
• when and where we write spec prose (WHATWG, CSS WG, ARIA)
• when we write tests
• when we write docs

[gregwhitworth]

Thanks for this @boazsender

scope (e.g. controls and component)
research process

I think the first 2 are a covered by the scope section and contribution docs (I'm sure they can be improved so PRs welcomed):
https://open-ui.org/charter#scope-of-work
https://open-ui.org/contribute#research-page

accessibility, privacy, and security review

Can you please expound on this - we have these in our Specification Template. We reference ARIA best practices for much of the work and when necessary loop in folks from the ARIA WG to weigh in on questions.

Privacy and security reviews are going to be much, much more limited in these scenarios since they're a composite of APIs provided by the web platform where the primary areas of vulnerabilities exist. Still there are areas for security (but not privacy so we should add that in so it's at least considered). The password reveal scenario comes to mind.

where to discuss use cases

I would assume Github is the place to start, are you thinking of something different here?

when and where we write spec prose (WHATWG, CSS WG, ARIA)

This is the section that I do think that we need to add in. I think it's worth providing concrete examples of "So you want to propose a new control/component. Here's the process....".

when we write tests

I would love to explore this further. We need a plan for what makes an Open UI compliant control/component and a test suite is the best approach here. Given your history here, what are your thoughts? I think we should probably spin up a new issue to discuss this.

when we write docs

Can you expound on this one

[boazsender]

Thanks for this @boazsender

Sure thing @gregwhitworth! Thanks for putting together this thoughtful and cross-cutting workflow for web UI. My interpretation of the CSS-WG conversation, and my overall thinking with this issue is to make a higher level process document that speaks to how we expect a control to go from web developer cow-path to accessible browser built-ins with HTML, CSS, and DOM interface.

I think there are some aspects of this implied in the templates, and other aspects documented in the Open UI contribute page. What I’m suggesting is to pull these steps together in a single document, and flesh out some of the unspoken details.

I've started to draft something in this (publicly viewable) google doc, and I’ve made you an editor, Greg: docs.google.com/document/d/1A...

I see three types of work here:

1. draw some boundaries about decision rights and
2. document those decisions
3. Provide guidance on how to do this work

scope (e.g. controls and component)
research process

I think the first 2 are a covered by the scope section and contribution docs (I'm sure they can be improved so PRs welcomed):
https://open-ui.org/charter#scope-of-work
https://open-ui.org/contribute#research-page

I think that's right. https://open-ui.org/contribute#proposal-page also has some great information. I really like the guidance to not “not re-define aspects of other specifications”.

I think it would be worth including these links in the higher level process document. I think the process documentation I'm describing could be implemented as edits to the contributing page, if you prefer. I personally think a dedicated process/working mode document would be clearer.

accessibility, privacy, and security review

Can you please expound on this - we have these in our Specification Template. We reference ARIA best practices for much of the work and when necessary loop in folks from the ARIA WG to weigh in on questions.

Privacy and security reviews are going to be much, much more limited in these scenarios since they're a composite of APIs provided by the web platform where the primary areas of vulnerabilities exist. Still there are areas for security (but not privacy so we should add that in so it's at least considered). The password reveal scenario comes to mind.

Similar to the above, I think spelling this out in a step by step “how we work” process document would help someone like me know how to approach and interact with Open UI.

I think the process document could link to the template, but also provide guidance around the work that goes into answering questions before the template is filled out, and following through after. The template is a frame in time of the process. For example: how do we consider the accessibility of the component in Open UIi? What steps are taken, who should I get input from, etc. Same for privacy and security, even if they are less common.

I’m thinking that there’s a lot of really great information in the spec template, that it would be worth pulling out into the working mode/process doc as well.

where to discuss use cases

I would assume Github is the place to start, are you thinking of something different here?

I think that works great! Some guidelines and expectations on this in the process doc could be worth while.

when and where we write spec prose (WHATWG, CSS WG, ARIA)

This is the section that I do think that we need to add in. I think it's worth providing concrete examples of "So you want to propose a new control/component. Here's the process....".

+1. I’ll try fleshing this out in the above linked doc a bit, and welcome your input. @zcorpan is also great at this, though busy, I know.

when we write tests

I would love to explore this further. We need a plan for what makes an Open UI compliant control/component and a test suite is the best approach here. Given your history here, what are your thoughts? I think we should probably spin up a new issue to discuss this.

I was thinking of WPT tests for the controls when they are implemented. I think it would be possible to tick the boxes of Open UI compliance within the scope of WPT. It would help to understand what “Open UI compliance” means from your perspective. Can you say more?

Some benefits of doing this under WPT include riding on existing WPT runner infra and 2-way sync flows with browser engines. We could have a special open-ui.fyi view of the results, or maybe even get wpt to adopt an open ui view.

Happy to start a new issue.

Started issue #206 to discuss this.

when we write docs

Can you expound on this one

Yes, sorry, this was a bit of private logic on my part. One of the things that I think ARIA Practices does so well is to make it the job of standards developers to think about how to explain the feature to web developers. I think this is good for two reasons:

1. It helps us maintain the documentation for the web, which right now, doesn’t have a clear funding model
2. It makes standards developer articulate things in web developer terms, which makes the standards process itself more accessible to first time participants, and also makes it easier for web developers to give feedback.

As an aside, I think APG could do this a bit better by not being a W3C Note, and Matt King is already on the job with the ARIA APG Redesign project.

[gregwhitworth]

Similar to the above, I think spelling this out in a step by step “how we work” process document would help someone like me know how to approach and interact with Open UI.

I agree 100%. I'll review the doc and circle back. I've added this to the agenda so that we can get eyeballs on it and discuss some of the larger adjustments here (horizontal review).

[bkardell]

[edit] comments all moved to the doc which is evolving so that the history here isn't just nonsense.

[gregwhitworth]

@bkardell you should be able to comment using this link

[boazsender]

Hey folks, @gregwhitworth, @una, @davatron5000 and I have written a new summary of the high level process in a stages outline:

0. Research
1. Open UI Draft
2. Community Draft
3. Recommendation
4. Finished

We've broken out these stages into separate steps in a new doc with more detail: https://docs.google.com/document/d/1Kbf4Ol_ZIgL0nYvDq2a6vQkbHrOdLr8EIF7HF20yFhw/edit

I've also reorganized the original working mode doc into this stages system with some "TODO" stubs left: https://docs.google.com/document/d/1A-9TdDSlrb9GARz63h_jhxuR4WQdj3OCebFOGGz4rw8/edit#heading=h.cfdz31gvc83h

[una]

Thanks for putting this together. I'd like to keep the stage names:

Stages:

0. Research
1. Editor's Draft
2. Community Draft
3. Recommendation
4. Finished <-- not even sure we need this

OpenUI Draft is implicit. Editors draft is more descriptive.

[boazsender]

PR #317 resolves this issue. @una, I went with "Editor's Draft".