Documentation requirements when launching new features

[Manuel Rego Casasnovas]

Hi.

In the new launching process
(https://www.chromium.org/blink/launching-features) we have a bunch of
places where we mention that people should work on documentation when
getting ready a feature for shipping.

Some sentences extracted from the document:
"You should also work with the documentation team to ensure your
features will be documented when shipped, and estimate when (in what
milestone) you would like to target shipping."
"You should get final signoff from Documentation, and update for any
changes in vendor signals."

First there's no info about how to communicate with that "documentation
team", so this might be hard to follow for external contributors. We
should add that to the document.

Apart from that nothing related to this appears in chromestatus or the
intent templates.
I don't know if we want to extend the templates adding this info, but we
probably should modify chromestatus to have something related to this.
Right now in chromestatus we just have an entry for "Doc link(s)" in the
stage "Dev trials and iterate on implementation" and it says: "Links to
design doc(s) (one URL per line), if and when available. [This is not
required to send out an Intent to Prototype. Please update the intent
thread with the design doc when ready]. An explainer and/or design doc
is sufficient to start this process. [Note: Please include links and
data, where possible, to support any claims.]"
This doc links, are more about implementation details as described
there, and they are unrelated with what the new process is asking for,
which is more close to user documentation.

What do you think?

Bye,
Rego

[Chris Harrelson]

I agree that good documentation is an important part of a successful feature.

However, I worry about overloading feature owners (almost always a software engineer) with yet more work, such as writing an MDN article. I think we (meaning me...) should try to get in place a sustainable process where the engineers can collaborate with tech writers / devrel on such documentation. At that point, I would definitely be in favor of requiring good documentation before approving an intent-toi-ship.

--
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/c0baf19d-4b36-0d62-fcd0-ada4da09cc56%40igalia.com.

[Manuel Rego Casasnovas]

On 05/11/2020 18:22, Chris Harrelson wrote:
> I agree that good documentation is an important part of a successful
> feature.
>
> However, I worry about overloading feature owners (almost always a
> software engineer) with yet more work, such as writing an MDN article. I
> think we (meaning me...) should try to get in place a sustainable
> process where the engineers can collaborate with tech writers / devrel
> on such documentation. At that point, I would definitely be in favor of
> requiring good documentation before approving an intent-toi-ship.

Yeah, I don't think feature owners should be in charge of this, or the
only ones at least. But I was trying to clarify what's currently written
in the launching process document. As it seems that documentation is a
requirement reading just reading it.

Bye,
Rego

> <mailto:blink-api-owners-discuss%2Bunsu...@chromium.org>.

[Joe Medley]

Gang,

DevRel and the WebStatus team are working on specifics. (Thanks to Chris for your interest in taking this obn.) We will be clarifying this in the near future. In the meantime, regard the references to documentation as placeholders that can be ignored, at least or the near future.

Joe

Joe Medley | Technical Writer, Chrome DevRel | jme...@google.com | 816-678-7195

If an API's not documented it doesn't exist.

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/d3a0a081-7fdb-a3fd-2133-723671578a9a%40igalia.com.

[Manuel Rego Casasnovas]

On 05/11/2020 21:50, 'Joe Medley' via blink-api-owners-discuss wrote:
> Gang,
>
> DevRel and the WebStatus team are working on specifics. (Thanks to Chris
> for your interest in taking this obn.) We will be clarifying this in the
> near future. In the meantime, regard the references to documentation as
> placeholders that can be ignored, at least or the near future.

It's good to know that things are moving regarding this.

Still we might want to update somehow the documentation at
https://www.chromium.org/blink/launching-features as it has been causing
some confusion to external contributors. There we mention that people
should talk to the documentation team and get a final signoff from them.
Maybe striking those sentences, maybe adding a small note about ignore
them for now or something like that.

Bye,
Rego

>
> Joe
> Joe Medley | Technical Writer, Chrome DevRel | jme...@google.com

> <mailto:jme...@google.com> | 816-678-7195
> /If an API's not documented it doesn't exist./

>
>
> On Thu, Nov 5, 2020 at 11:56 AM Manuel Rego Casasnovas <re...@igalia.com
> <mailto:re...@igalia.com>> wrote:
>
>
>
> On 05/11/2020 18:22, Chris Harrelson wrote:
> > I agree that good documentation is an important part of a successful
> > feature.
> >
> > However, I worry about overloading feature owners (almost always a
> > software engineer) with yet more work, such as writing an MDN
> article. I
> > think we (meaning me...) should try to get in place a sustainable
> > process where the engineers can collaborate with tech writers / devrel
> > on such documentation. At that point, I would definitely be in
> favor of
> > requiring good documentation before approving an intent-toi-ship.
>
> Yeah, I don't think feature owners should be in charge of this, or the
> only ones at least. But I was trying to clarify what's currently written
> in the launching process document. As it seems that documentation is a
> requirement reading just reading it.
>
> Bye,
>   Rego
>
> >
> > On Thu, Nov 5, 2020 at 7:51 AM Manuel Rego Casasnovas
> <re...@igalia.com <mailto:re...@igalia.com>

> >     <mailto:blink-api-owners-discuss%2Bunsu...@chromium.org
> <mailto:blink-api-owners-discuss%252Buns...@chromium.org>>.

> >     To view this discussion on the web visit
> >   
>  https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/c0baf19d-4b36-0d62-fcd0-ada4da09cc56%40igalia.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
> <mailto:blink-api-owners-discuss%2Bunsu...@chromium.org>.
> To view this discussion on the web visit

> https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/d3a0a081-7fdb-a3fd-2133-723671578a9a%40igalia.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

> <mailto: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/CAJUhtG_ypxzF47HBYTgT8%3D_-R%3D2TiEWiTQXAtP16VQqfOYRFQQ%40mail.gmail.com
> <https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/CAJUhtG_ypxzF47HBYTgT8%3D_-R%3D2TiEWiTQXAtP16VQqfOYRFQQ%40mail.gmail.com?utm_medium=email&utm_source=footer>.

[Philip Jägenstedt]

One relevant upcoming change here is that MDN is moving to maintaining its content on GitHub:

https://hacks.mozilla.org/2020/10/mdn-web-docs-evolves-lowdown-on-the-upcoming-new-platform/

I believe this will make it much easier for engineers and tech writers to collaborate on the documentation for a feature before any of it gets merged, which is not really possible now. Once that is in place, it will be more reasonable for us to require a ready-to-go documentation PR as part of the launch process.

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/00be9667-b85c-2db8-3b8b-7e1295e3b12b%40igalia.com.

[Joe Medley]

Yeah, we're taking that into account.

Joe Medley | Technical Writer, Chrome DevRel | jme...@google.com | 816-678-7195

If an API's not documented it doesn't exist.