search

openjs-foundation / standards

a repository for documenting and coordinating the foundation's web standards work
Apache License 2.0
80 stars 21 forks source link

Concise Guide to Participating in Web Standards Document WIP #190

Closed jorydotcom closed 1 year ago

jorydotcom commented 2 years ago

Taking inpsiration from the OpenSSF's recent concise guides, we are collaborating on a "Concise Guide" of our own.

Action: add suggested bullets for discussion / collaboration at next meeting here

michaelchampion commented 2 years ago

I've been editing https://docs.google.com/document/d/1yDxUCnvZC23HfZXOz7OAbyWHZqqqNXBZHk0y3GBeIds/edit but don't see anyone else editing or commenting.

Current title and questions are: Concise Guide to Improving Web Standards

I'm not at all sure others agree with my draft answers to these questions, and I'm sure there are more questions JS developers have about web standards. Please take a look before the 09-20 meeting ;-)

dtex commented 2 years ago

Everything rings true, but one answer bothers me a little.

How to read standards? Don’t, unless you are implementing the standard or testing an implementation.

I agree that it is rarely the best starting point for someone looking to learn, but that's not really our audience here. I'd also argue that not all specs are equally obtuse, and some are quite approachable. Finally, the tone here could be considered condescending, and we want to encourage people to step outside their comfort zone.

oh, and sometimes even in our roles as developers, we really do need to look at specs. I once found myself in a pickle that could only be understood by digging into 262.

Maybe:

"The language found in specifications can sometimes be difficult to digest. The explanations and tutorials on sites such as MDN Web Docs https://developer.mozilla.org/en-US/ are generally more appropriate for developers looking to learn.

Nevertheless, sometimes diving into a specification will be necessary. Many of those specs will have their own "How to Read" documents, such as this for ECMA-262. Also, this post is old but still very helpful for anyone new to standards."

Sorry to make it longer, but "Concise" is a skill that eludes me.

michaelchampion commented 2 years ago

Thanks, that's a great edit! I've incorporated into the document.

jorydotcom commented 1 year ago

After latest revision, last call for notes/comments. Jory will incorporate these in time for the March 7 meeting, and we will collect +1s to ship at that time.