Tips for getting involved in the standards process

tips-involved.md

This gist is meant to help me compile "tips" for getting involved in the standards process. It will be used as a source of material for a talk I'm giving at LXJS in a couple days. The tips are meant to be somewhat tactical, i.e. provide concrete advice for first-timers, and not general sweeping statements about how standards bodies work in the abstract.

If you have any additional tips, please leave them in a comment or email them to me at [email protected], and they'll hopefully make it into my presentation.

The Tips

Lurk First

As with all new communities you're joining, you'll get better results if you lurk first, both in IRC and on the relevant mailing lists. You'll get to know who's active in what area; what kind of topics are on the group's radar; which issues are contentious; and even basic stuff like how to write emails (prefer plain text, never top-quote).

Solution Time is Later

Don't bust onto the mailing list, multi-page spec in hand, telling us about this amazing new API that we really should add to the standard. Instead, outline the problem you have. You need to get agreement that this is a problem, and that it cannot be solved with existing technology, and that implementers are interested in solving it. Only then it is solution time.

(Derived from advice from the WHATWG FAQ.)

Understand the Constraints

You're working within the web platform, so any solution must respect the existing platform. This can range from its security model, to the fact that APIs are exposed in JavaScript, to the idea that we do not want to introduce data races via multithreading primitives.

As an example, some people recently have been doing some great work reimagining streams in the Node.js space. But when I tried to help them flesh out their proposal into something that we could bring into the browser, they said "No, I don't like objects having to have prototypes and constructors; we should just use object literals for streams." This just doesn't work. Our APIs in JavaScript and on the web, regardless of your personal preferences, are going to use a constructor with a prototype. We're not going to give our APIs multiple-personality disorder just to satisfy your style of writing code; for better or for worse, the standard library has a way of working that you need to be able to work within if you want to contribute to it. It's like coding style: I hate comma-first, but if I'm contributing to a project which uses it, I'm not going to insist that my pull request be comma-last.

Concede Defeat, and Don't Retread

If a decision has been made, and all the implementers are on board, it's very unlikely you're going to come up with a super-brilliant argument that dissuades them. Instead, you'll just waste everyone's time as they patiently explain to you arguments that have already been made, and why the decision we've arrived at is the prevalent practice. Save your energy for battling new bad ideas.

Example: ES6 and the web platform have settled on promises as their async primitive, after years of stumbling through horrible async APIs with onerror, onsuccess, onresult, whatever. This is great! Now we need to build on this bedrock. Insisting that your async APIs should be Node.js-style callbacks is not going to be helpful; you're re-treading a battle that was already fought, and just not contributing productively.

Leave Your Sense of Logic at the Door

The web platform sucks, and everyone knows it. It has tons of historical warts, which we can't fix because the web depends on it. Don't blame us for DOM0, or with, or defaultValue vs. value! In general, don't blame us for the existence of sucky APIs. We can't remove them, and we have to integrate with them. The only thing we can do is move away from them when adding new features.

The web had a deeply confused childhood, derived from multiple competing browser vendors doing whatever they pleased, and others copying them, including their bugs. We're in a better place now, but we still have to build on top of the existing platform; we can't start over.

(Derived from the WHATWG IRC channel topic)

Maybe there's stuff in http://www.w3.org/TR/html-design-principles/ you could mine. e.g.,

Avoid Needless Complexity

In proposing solutions to problems and in discussing solutions proposed by other peoples, favor simple solutions over complex ones. Simpler solutions are easier for user agents to implement, more likely to be interoperable, and easier for authors to understand.

Focus on Solving Real Problems

In proposing solutions to problems and in discussing solutions proposed by other peoples, favor pragmatic solutions to problems that web content faces today, rather than abstract architectures that don't address any actual existing need.

The title "Leave Your Sense of Logic at the Door" is a bit too cynical me thinks. The reality is that things actually are logical when you have the full picture.

I would chose to express this point something like this:
Objects in rear-view mirror are more complicated than they appear. APIs that seem odd, illogical or poorly designed often make a lot more sense when you have an understanding of their historical context and/or of the applicable design constraints, such as portability, backwards compatibility, conformance to other related standards, considerations for how browsers are implemented, etc.

Agreeing with @junov, you probably mean “leave your indignation at the door”.

This was partially already mentioned:

"Focus on Solving Real Problems" << That's a tip I was told as well: Start with "what is the use case you try to solve?" kind of question. Once you have answered it, outline a possible solution (if you have one) without going into too much details. Try to keep your email short and get to the point. Don't waist your time (and the one of others) writing a long email that gets rejected because of trivial thing (e.g. the idea was brought up before and got rejected).

Agree with @kriskowal