when are explainers needed for spec issues?

[Ben Kelly]

Hello API owners,

I've noticed recently that owners have been asking for explainer documents for web API changes that have been resolved via spec issues.  Generally these are smaller changes and often already have vendor consensus.  I am about to start working on one of these spec issues and I am curious:

What is the bar for requiring an explainer doc?  When do I need to write one and when is the description in the spec issue enough?

While I'm sure there are marginal benefits to writing an additional explainer document, it seems for many changes it will largely duplicate the content in the spec issue and at some point becomes busy work without a significant benefit.

FWIW, in my specific case I am planning to work on service worker issue 1512, but it would be nice to have a way to reason about this for future work.

Thanks.

Ben

[Chris Harrelson]

Hi Ben,

I agree with you that small changes to specs might not need explainers, in particular in cases where the other browser implementations already ship the feature or the use case is particularly obvious. However, even when adding a "small" change to an existing spec, such as adding a new property, it's good to be in the habit of writing an explainer for the use cases for which the property is useful. In some cases I think it's ok to write an "explainer" which is just a long-ish comment on a github issue. Your intent (for service-worker issue 1512) might fall into this category.

If you have a particular example where you think the bureaucracy was excessive, could you post it here for consideration? We'd like to keep the process lightweight when possible.

Thanks,

Chris

--
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/CAK7rkMgbw4i4JF3M7ehyHC7QyAD%3DEyok-Cijx0AgTJA1hZHGSw%40mail.gmail.com.

[Daniel Bratell]

An explainer is pretty much mandatory but it doesn't have to be an explainer "document". It can be 3 sentences if that is all it takes to give people the necessary background and motivation for the feature.

The purpose is to give people that know nothing about the area and background a way to get up to speed quickly. Without such a document, people may end up looking at a feature from the wrong angle.

I think it's causing confusion because to the people that have worked on the feature for a long time, everything in the explainer is so obvious and it's hard to see why it would have to be documented.

As for writing just another document, I think the text in an explainer often may overlap quite a lot with the summary in chromestatus/webstatus, and maybe even with the introduction in a spec issue or specification. That should allow some text reuse. (aka Ctrl-C Ctrl-V)

/Daniel

[Ben Kelly]

On Thu, Jul 30, 2020 at 1:22 PM Chris Harrelson <chri...@chromium.org> wrote:

Hi Ben,

I agree with you that small changes to specs might not need explainers, in particular in cases where the other browser implementations already ship the feature or the use case is particularly obvious. However, even when adding a "small" change to an existing spec, such as adding a new property, it's good to be in the habit of writing an explainer for the use cases for which the property is useful. In some cases I think it's ok to write an "explainer" which is just a long-ish comment on a github issue. Your intent (for service-worker issue 1512) might fall into this category.

If you have a particular example where you think the bureaucracy was excessive, could you post it here for consideration? We'd like to keep the process lightweight when possible.

The recent case that made me wonder if I understand the balance API owners are looking for was the service worker FetchEvent.handled intent.  Ting ended up writing an explainer upon request:

https://github.com/tingshao/FetchEvent.handled/blob/master/explainer.md

Which is extremely close to the content in the original comment of the spec issue:

https://github.com/w3c/ServiceWorker/issues/1397

[Daniel Bratell]

To follow up on my own post. Today we link to the W3C requirements for an explainer, which is an ambitious set of requirements. I don't think they are bad requirements but I think they are overkill for many small changes/features.

In an explainer I mainly look for relatively simple answers to these questions:

* What is this about in layman terms?

* Why do we want to have this modification in Chromium?

Even if this information is available elsewhere, in mail threads, github issues or elsewhere, I want this information before I start reading all the heated discussion, evolving opinions and lengthy descriptions.

If these questions can be answered in a couple of sentences (not always easy, but sometimes it is), that would satisfy my needs.

/Daniel

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/3573364d-5f60-9af3-96d1-94f857fb5d97%40gmail.com.

[Yoav Weiss]

Thanks for starting this thread, Ben! 

IMO, the goal for explainers is two-fold:

1) API owners may not be familiar with the feature or even this area, and an explainer outlining the feature and the use cases it is solving would give them better understanding of *what the thing is*, which can help when reading other artifacts, and assessing if this is something we actually want to ship.

2) Web developers and other interested folks that watch these threads can have a better understanding of what we're shipping and why it's useful for them, without plowing through GH issues and PRs.

On Thu, Jul 30, 2020 at 7:33 PM Ben Kelly <wande...@chromium.org> wrote:

On Thu, Jul 30, 2020 at 1:22 PM Chris Harrelson <chri...@chromium.org> wrote:

Hi Ben,

I agree with you that small changes to specs might not need explainers, in particular in cases where the other browser implementations already ship the feature or the use case is particularly obvious. However, even when adding a "small" change to an existing spec, such as adding a new property, it's good to be in the habit of writing an explainer for the use cases for which the property is useful. In some cases I think it's ok to write an "explainer" which is just a long-ish comment on a github issue. Your intent (for service-worker issue 1512) might fall into this category.

If you have a particular example where you think the bureaucracy was excessive, could you post it here for consideration? We'd like to keep the process lightweight when possible.

The recent case that made me wonder if I understand the balance API owners are looking for was the service worker FetchEvent.handled intent.  Ting ended up writing an explainer upon request:

https://github.com/tingshao/FetchEvent.handled/blob/master/explainer.md

Which is extremely close to the content in the original comment of the spec issue:

https://github.com/w3c/ServiceWorker/issues/1397

That's a good example.

The original thread is over 2000 words, that outline the journey this addition went through (proposal, discussions and finally - resolution). That's great for diving in, but less great when you just want to quickly understand what it is that we're trying to ship and why.

The small-ish explainer (around 370 words by my count) is a summary of where that thread landed, which is perfectly sufficient to convey where we landed and why.

I'd also be fine with e.g. a summary of the issue (which would be more or less equivalent to the explainer) edited into the original post on the issue, or added as a comment to its bottom. I don't care about the explainer text being in a separate document, on GH or inline, as long as I (and busy web developers) can quickly understand what this is about and what use-cases it solves.

 

Thanks,

Chris

On Thu, Jul 30, 2020 at 8:46 AM Ben Kelly <wande...@chromium.org> wrote:

Hello API owners,

I've noticed recently that owners have been asking for explainer documents for web API changes that have been resolved via spec issues.  Generally these are smaller changes and often already have vendor consensus.  I am about to start working on one of these spec issues and I am curious:

What is the bar for requiring an explainer doc?  When do I need to write one and when is the description in the spec issue enough?

While I'm sure there are marginal benefits to writing an additional explainer document, it seems for many changes it will largely duplicate the content in the spec issue and at some point becomes busy work without a significant benefit.

FWIW, in my specific case I am planning to work on service worker issue 1512, but it would be nice to have a way to reason about this for future work.

Thanks.

Ben

--
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/CAK7rkMgbw4i4JF3M7ehyHC7QyAD%3DEyok-Cijx0AgTJA1hZHGSw%40mail.gmail.com.

--
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/CAK7rkMg21Dn75V2%3DDdSvb_OinKVaQN77jwUKx9o%3DoaezHwBsqA%40mail.gmail.com.

[Yoav Weiss]

On Thu, Jul 30, 2020 at 9:41 PM Daniel Bratell <brat...@gmail.com> wrote:

To follow up on my own post. Today we link to the W3C requirements for an explainer, which is an ambitious set of requirements. I don't think they are bad requirements but I think they are overkill for many small changes/features.

In an explainer I mainly look for relatively simple answers to these questions:

* What is this about in layman terms?

* Why do we want to have this modification in Chromium?

I'd also add a code sample to this, when relevant.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/1fa1371a-25eb-9187-3653-10cfba7467ab%40gmail.com.

[PhistucK]

A code sample would be extremely helpful!

☆PhistucK

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

[Ben Kelly]

On Fri, Jul 31, 2020 at 2:33 AM Yoav Weiss <yoav...@google.com> wrote:

Thanks for starting this thread, Ben! 

IMO, the goal for explainers is two-fold:

1) API owners may not be familiar with the feature or even this area, and an explainer outlining the feature and the use cases it is solving would give them better understanding of *what the thing is*, which can help when reading other artifacts, and assessing if this is something we actually want to ship.

2) Web developers and other interested folks that watch these threads can have a better understanding of what we're shipping and why it's useful for them, without plowing through GH issues and PRs.

On Thu, Jul 30, 2020 at 7:33 PM Ben Kelly <wande...@chromium.org> wrote:

On Thu, Jul 30, 2020 at 1:22 PM Chris Harrelson <chri...@chromium.org> wrote:

Hi Ben,

I agree with you that small changes to specs might not need explainers, in particular in cases where the other browser implementations already ship the feature or the use case is particularly obvious. However, even when adding a "small" change to an existing spec, such as adding a new property, it's good to be in the habit of writing an explainer for the use cases for which the property is useful. In some cases I think it's ok to write an "explainer" which is just a long-ish comment on a github issue. Your intent (for service-worker issue 1512) might fall into this category.

If you have a particular example where you think the bureaucracy was excessive, could you post it here for consideration? We'd like to keep the process lightweight when possible.

The recent case that made me wonder if I understand the balance API owners are looking for was the service worker FetchEvent.handled intent.  Ting ended up writing an explainer upon request:

https://github.com/tingshao/FetchEvent.handled/blob/master/explainer.md

Which is extremely close to the content in the original comment of the spec issue:

https://github.com/w3c/ServiceWorker/issues/1397

That's a good example.

The original thread is over 2000 words, that outline the journey this addition went through (proposal, discussions and finally - resolution). That's great for diving in, but less great when you just want to quickly understand what it is that we're trying to ship and why.

The small-ish explainer (around 370 words by my count) is a summary of where that thread landed, which is perfectly sufficient to convey where we landed and why.

Not to over index on this one issue, but you didn't have to read the entire issue thread.  The explainer is nearly identical to the original issue comment describing the use cases.

 

I'd also be fine with e.g. a summary of the issue (which would be more or less equivalent to the explainer) edited into the original post on the issue, or added as a comment to its bottom. I don't care about the explainer text being in a separate document, on GH or inline, as long as I (and busy web developers) can quickly understand what this is about and what use-cases it solves.

Thanks.  I'll make a point of summarizing in the intent email and referencing specific github comments that contain the explainer information where appropriate.