Improving the documentation behind launch process requirements

[Domenic Denicola]

Hi API OWNERS,

Recently there have been a number of updates discussed on this list to the Intent to Prototype/Experiment/Ship templates, aimed at clarifying the requirements. But, some discussions with coworkers revealed that the reasoning behind these requirements is not always clear. This is also evident externally, as seen in some points of Manuel's message to this list from February, plus various discussions with web developers.

As such, I've drafted up a document, tentatively titled "Launching Web Platform Features Well", which attempts to capture the reasoning behind the Blink launch process, as well as crisp up exactly what artifacts we expect Chromium developers to produce when launching a feature. For example, we have fields for "Explainer" and "Design Doc/Spec" in the Intent templates, but no reasoning explaining why these artifacts are important; this document attempts to address that.

I'd love to get the API OWNERS thoughts on this document, with the aim of eventually promoting it to official documentation on chromium.org. (Probably either replacing or merging with the existing Guidelines for Web Platform Changes.)

This could also fit into the upcoming launch process update that Johnny and others are working on. For example, the new tooling being designed could link out to the appropriate sections of my document to provide background, or have more formal ways of capturing wide review and specification mentoring.

Best,

-Domenic

[Rick Byers]

Thanks Domenic, Your doc definitely adds useful context and advice. I left a couple minor notes, but unsurprisingly I agree with everything you said. My only substantial feedback is that I think you undersold the role of testing.

The thing I personally struggle most with here is how do we give people the most concise yet relevant and helpful information they need knowing that most engineers won't spend much time reading any docs around this stuff. Hopefully the new tooling and process +Johnny and +Chris as putting into place will solve that main problem and have helpful "for more information" links to pages like your doc. I don't have good intuition or advice on how to organize our communication here myself.

Rick

--
You received this message because you are subscribed to the Google Groups "blink-api-owners-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-api-owners-d...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/CAM0wra-mL%3D6HE-rBK7-0oxjWioYRq34ZKsHRASD%3DMGRp5ZKgRw%40mail.gmail.com.

[Daniel Bratell]

Sorry for missing this (and thanks for Rick bringing it to the surface again!)!

The document is packed full of useful information and knowledge and I would love to transplant that information into everyone's mind. That said, the main obstacle will be to get the relevant people to read it.

My impression is that that the process feels too involved for those that aren't using it very often (which is most people) and one more thing to read in advance might increase that feeling instead of helping. Question to all: Could all information in the excellent document be compressed or portioned out in a way that would make it available in bite size chunks at the right time?

/Daniel

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/CAFUtAY9qMcYB%2BXFmzjusG%3DgPoyaaxgoWqBki7HcrpvA_mMn%2BzA%40mail.gmail.com.