Feature documentation as part of the process

[Yoav Weiss (@Shopify)]

Hey folks!

I recently found that a feature we shipped in M126 never got any proper documentation in MDN or elsewhere.

While it's true that some of the eng orgs that are shipping features in Chromium have DevRel and tech writers, I believe the ownership for documentation should eventually lie on the engineers shipping the features. Our process should nudge engineers in that direction.

So, I think we should add a question to our process regarding a documentation plan. The answers to that may be:
* This is too small to document
* I'm planning to open MDN PRs
* I've lined up devrel resources to lead this

* Something else??

That would require the engineers that ship features to think about this, and do what's necessary to ensure documentation happens. It might also be useful for devrel orgs if this turned documentation projects from to a model where engineers explicitly request documentation help, rather than devrel orgs having to pay attention to everything's shipping and try to fill in gaps.

I don't think we should block shipping on documentation already existing, but having a plan seems useful.

What do y'all think?

Cheers :)

Yoav

[Domenic Denicola]

We discussed this in the past: https://groups.google.com/a/chromium.org/g/blink-api-owners-discuss/c/DHxPFzcGXGg/m/wEPjtiWCAwAJ

I am sympathetic to Chris's point at the time:

> I worry about overloading feature owners (almost always a software engineer) with yet more work, such as writing an MDN article.

I think asking for a documentation plan might be reasonable, but I think it should be OK if the plan is "we don't have anyone staffed for this, sorry!"

And even then, I'm a bit hesitant about adding even more fields to the already-fairly-onerous ChromeStatus process. (This is the third proposal for a new ChromeStatus field I've heard in recent memory, with the other two being around browser automation and privacy threat models. I understand that everyone really wants their priority to be included in the template! But we have to be cautious about the aggregate effects. I wonder if we could remove some of the lesser-used fields, e.g. "Adoption expectation" or "Ergonomics risks", before adding new ones.)

Even with that, I'm not sure how I would fill this out as a Googler feature owner. Our current process is, the Google documentation team picks the features they want to document, on some timetable which is weeks to months after the I2S has been approved. (Usually close to stable release.) I don't think there's a mechanism for me to know in advance whether my feature will rise above the cutoff on the feature documentation team's priority list.

So I'd worry that if we added this field to the template, the Googlers would end up filling out something like "The plan is that maybe the Google documentation team will pick this up, but I can't know at this time." Maybe that's fine, if the goal is to raise awareness among non-Googler contributors? Non-Googler contributors were a major subject of discussion in the previous thread.

--
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 visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/CAOmohSKW88o8WhZoOPF9V-g3A7YM0ws-jEByp2Obvr%3D%2Bjxn-_Q%40mail.gmail.com.

[Rachel Andrew]

Hi Yoav

This biggest issue here was that the feature wasn't updated on Chrome Status. We didn't know it was shipping, so it completely missed the process that does exist.

We do have a process in Chrome to track docs needs, and get most things documented. However, I don't have resources to go poking around Chromium source to find the things that were not flagged as shipping in Chrome Status.

So, the most helpful thing people can do is to make sure their Chrome Status entry is up to date—that said, I'm always happy if someone else wants to contribute docs! It might be good for Chrome Status to have a field for people to indicate if they are doing that. So I can account for it when I intake the current beta (that's really the point at which MDN is happy to accept docs for a Chrome-first feature).

Rachel