Improve documentation for spec mentors. [website : main]
Jeffrey Yasskin (Gerrit)
Attention is currently required from: Domenic Denicola, Yoav Weiss.
Jeffrey Yasskin would like Yoav Weiss and Domenic Denicola to review this change.
Improve documentation for spec mentors.
Change-Id: I50a197f153758a445e53227c5dbb3c0e857f9a94
---
M site/blink/spec-mentors/index.md
1 file changed, 82 insertions(+), 2 deletions(-)
To view, visit change 4233971. To unsubscribe, or for help writing mail filters, visit settings.
Jeffrey Yasskin (Gerrit)
Attention is currently required from: Domenic Denicola, Yoav Weiss.
1 comment:
Patchset:
I'm trying to improve our explanation of what spec mentors are supposed to do. What do y'all think?
To view, visit change 4233971. To unsubscribe, or for help writing mail filters, visit settings.
Yoav Weiss (Gerrit)
Attention is currently required from: Domenic Denicola, Jeffrey Yasskin.
Patch set 1:Code-Review +1
2 comments:
Patchset:
LGTM % link issues, but let's wait for Domenic to review
File site/blink/spec-mentors/index.md:
Patch Set #1, Line 185:
Ship](http://localhost:8080/blink/launching-features/#new-feature-prepare-to-ship),I'm guessing you didn't mean localhost here..
To view, visit change 4233971. To unsubscribe, or for help writing mail filters, visit settings.
Jeffrey Yasskin (Gerrit)
Attention is currently required from: Domenic Denicola.
2 comments:
Patchset:
LGTM % link issues, but let's wait for Domenic to review
Yep, I'll wait for Domenic next week, and then I'll add an OWNER to review.
File site/blink/spec-mentors/index.md:
Patch Set #1, Line 185:
Ship](http://localhost:8080/blink/launching-features/#new-feature-prepare-to-ship),I'm guessing you didn't mean localhost here..
Oops, indeed. Fixed.
To view, visit change 4233971. To unsubscribe, or for help writing mail filters, visit settings.
Dominic Farolino (Gerrit)
Attention is currently required from: Domenic Denicola, Jeffrey Yasskin.
2 comments:
File site/blink/spec-mentors/index.md:
Patch Set #2, Line 129:
specification that will eventually land in ChromiumThe spec doesn't really land in Chromium, right? What about "writing a specification for a feature being developed in Chromium"? This also captures the idea that features are usually in development by the time specification writing comes around.
Patch Set #2, Line 137:
(spec-m...@chromium.org)I'm not sure this or the brackets are necessary. If we use GitHub MD rules then I think they are not: https://gist.github.com/domfarolino/c218bead31869de41bdc446070e795ba (view "Raw" form of that MD file).
To view, visit change 4233971. To unsubscribe, or for help writing mail filters, visit settings.
Jeffrey Yasskin (Gerrit)
Attention is currently required from: Domenic Denicola, Dominic Farolino.
2 comments:
File site/blink/spec-mentors/index.md:
Patch Set #2, Line 129:
specification that will eventually land in Chromium
The spec doesn't really land in Chromium, right? What about "writing a specification for a feature b […]
Sure. I also tried "writing a specification for a feature that will eventually land in Chromium", but I think your text's implication is right that we want to aim spec mentorship at things with active development, and not at folks outside the project who also want help convincing us to implement.
I'm not sure this or the brackets are necessary. […]
The 11ty configuration we're using here doesn't auto-link email addresses. I checked. :) I think we could add a markdown-it plugin to https://source.chromium.org/chromium/chromium/src/+/main:docs/website/.eleventy.js to make it do so, but I didn't want to get distracted finding the right one.
To view, visit change 4233971. To unsubscribe, or for help writing mail filters, visit settings.
Dominic Farolino (Gerrit)
Attention is currently required from: Domenic Denicola, Jeffrey Yasskin.
Patch set 3:Code-Review +1
Domenic Denicola (Gerrit)
Attention is currently required from: Jeffrey Yasskin.
Patch set 3:Code-Review +1
4 comments:
Patchset:
Thanks for doing this!
LGTM with nits, and perhaps a substantive discussion about how solution-focused explainers should be.
File site/blink/spec-mentors/index.md:
Patch Set #3, Line 101:
## For Spec Mentors"For spec mentors" (lowercase)
Patch Set #3, Line 137:
[spec-m...@chromium.org](spec-m...@chromium.org).mailto: in the URL, or use https://groups.google.com/a/chromium.org/g/spec-mentors instead
Patch Set #3, Line 153:
the problem.I'm unsure about this last sentence. In practice, that doesn't seem to be how we work.
Maybe soften it to something like "Especially in the initial stages, an explainer should remain open about the possibility of alternative solutions, e.g., by documenting alternatives considered or calling out areas where better ideas are appreciated."
To view, visit change 4233971. To unsubscribe, or for help writing mail filters, visit settings.
Jeffrey Yasskin (Gerrit)
Attention is currently required from: Domenic Denicola.
Patch set 4:Auto-Submit +1Commit-Queue +1
4 comments:
Patchset:
Thanks for the review!
File site/blink/spec-mentors/index.md:
Patch Set #3, Line 101:
## For Spec Mentors"For spec mentors" (lowercase)
Done
mailto: in the URL, or use https://groups.google.com/a/chromium. […]
URLs: how do they work?
Thanks!
Patch Set #3, Line 153:
the problem.
I'm unsure about this last sentence. In practice, that doesn't seem to be how we work. […]
My text would be a change to how we usually do things, although it would put us more in line with https://whatwg.org/faq#adding-new-features and with what Mozilla wishes we'd do.
I've adopted a variation of your text so that we can merge the rest of the change, but we should keep thinking about how we want to guide our teams.
To view, visit change 4233971. To unsubscribe, or for help writing mail filters, visit settings.
Jeffrey Yasskin (Gerrit)
Attention is currently required from: Domenic Denicola, Elly Fong-Jones.
Jeffrey Yasskin would like Elly Fong-Jones to review this change.
Improve documentation for spec mentors.
Change-Id: I50a197f153758a445e53227c5dbb3c0e857f9a94
---
M site/blink/spec-mentors/index.md
1 file changed, 82 insertions(+), 2 deletions(-)
To view, visit change 4233971. To unsubscribe, or for help writing mail filters, visit settings.
Jeffrey Yasskin (Gerrit)
Attention is currently required from: Domenic Denicola, Elly Fong-Jones.
1 comment:
Patchset:
Hey Elly, could I get an OWNERS review? (Do you think it's time to put our own OWNERS file in /blink/spec-mentors/?)
To view, visit change 4233971. To unsubscribe, or for help writing mail filters, visit settings.
Elly Fong-Jones (Gerrit)
Attention is currently required from: Domenic Denicola, Jeffrey Yasskin.
Patch set 4:Code-Review +1
5 comments:
Patchset:
lgtm as-is, but I have a couple of questions/comments
File site/blink/spec-mentors/index.md:
Patch Set #4, Line 152:
should make it clearalso the feature team actually *should be* open to that - it seems good for the spec mentor to coach the author towards having an open mind to alternative approaches, which I suspect is not always the case
Patch Set #4, Line 172:
similar IP protectionwhat does this mean?
Patch Set #4, Line 174:
a personal repositoryis there no repository for chromium internet-drafts?
Patch Set #4, Line 180:
Reviewing the specificationPerhaps also: "Review the specification for good technical writing. It should be clear enough that someone not familiar with any specific implementation of the feature could write a working new one from the specification." or something?
To view, visit change 4233971. To unsubscribe, or for help writing mail filters, visit settings.
Jeffrey Yasskin (Gerrit)
Attention is currently required from: Domenic Denicola, Elly Fong-Jones.
Patch set 5:Auto-Submit +1
5 comments:
Patchset:
Thanks for the review! I'll submit this tomorrow evening unless I hear more suggestions.
File site/blink/spec-mentors/index.md:
Patch Set #4, Line 152:
should make it clear
also the feature team actually *should be* open to that - it seems good for the spec mentor to coach […]
Good point. I've rearranged the sentence and adding a bit about coaching for more flexibility.
Patch Set #4, Line 172:
similar IP protectionwhat does this mean?
I added a sentence at the start of this section about why we put proposals in incubation venues in the first place. That introduces the notion of IP protection, which I hope makes this mention clearer?
Patch Set #4, Line 174:
a personal repositoryis there no repository for chromium internet-drafts?
Nope. We'd want a whole organization so that I-Ds can be transferred to their eventual WGs, and I'm not sure there's enough of a problem with using personal repos to justify setting up a central place. We have gotten some complaints from other browsers about using personal repos for explainers, but we're trying to handle those by pushing explainers into CGs earlier.
Patch Set #4, Line 180:
Reviewing the specification
Perhaps also: "Review the specification for good technical writing. […]
LGTM; I've added that.
There's a bunch of other guidance we should probably add here, but I wanted to get a framework in place so we can improve it incrementally.
To view, visit change 4233971. To unsubscribe, or for help writing mail filters, visit settings.
Jeffrey Yasskin (Gerrit)
Attention is currently required from: Domenic Denicola, Elly Fong-Jones.
Patch set 5:Commit-Queue +2
chromium-website-scoped@luci-project-accounts.iam.gserviceaccount.com (Gerrit)
chromium-we...@luci-project-accounts.iam.gserviceaccount.com submitted this change.
4 is the latest approved patch-set.
The change was submitted with unreviewed changes in the following files:
```
The name of the file: site/blink/spec-mentors/index.md
Insertions: 15, Deletions: 6.
The diff is too large to show. Please review the diff.
```
Improve documentation for spec mentors.
Change-Id: I50a197f153758a445e53227c5dbb3c0e857f9a94
Reviewed-on: https://chromium-review.googlesource.com/c/website/+/4233971
Reviewed-by: Domenic Denicola <dom...@chromium.org>
Auto-Submit: Jeffrey Yasskin <jyas...@google.com>
Reviewed-by: Yoav Weiss <yoav...@chromium.org>
Reviewed-by: Dominic Farolino <d...@chromium.org>
Reviewed-by: Elly Fong-Jones <elly...@chromium.org>
Commit-Queue: Jeffrey Yasskin <jyas...@google.com>
---
M site/blink/spec-mentors/index.md
1 file changed, 98 insertions(+), 2 deletions(-)