fix: Update document shepherd writeup template based on community review#4042
Conversation
rjsparks
left a comment
rjsparks
left a comment
There was a problem hiding this comment.
I've reviewed these changes with my community member hat on, and find them to all be helpful.
|
It would be easier to review this is the content changes were in a separate PR from the markup/formatting changes. |
|
@cabo, does the revised question 5 work for you? |
|
@larseggert : Yes, that works for me. |
1e86a1c to
f073981
Compare
|
One more question that seems to have fallen through the cracks: Question 7 is odd, in that it's not horizontal across all specs; it's limited to just YANG documents. To me, the logical thing to do is to fold it into question 6 or 10 (with less detail). Alternatively, if we're going to have vertical shepherd criteria like this, it would be good to understand how to get onto the list; e.g., there are some HTTP-specific questions I'd like to ask. |
YANG is special :-) Seriously though, it does require quite a bit of extra checks. |
What makes YANG special is that it is the only FDT (format description technique) that we have embraced at a level that requires tool support throughout the process. Expect this list to grow as we find other FDTs that we want to take to this level. |
|
OK, so I'd propose a new item then (probably right after 7):
|
This looks a lot like we should have a separate document with pointers how to check for the guidelines of specific verticals. That document could move faster than the shepherd template, which would reference it. |
|
That would work for me. |
|
I want to push back here. The purpose of the document writeup is to inform the responsible AD and the rest of the IESG. If we feel that we need to ask a specific question about YANG, we should be free to do so. On the flip side, if we don't feel like we need to for HTTP, that is fine, too (and not necessarily a bad sign.) |
|
Whatever you decide the shepherd needs to report about, I want that other document! |
|
@larseggert that kind of sends a message that the IESG is more interested in YANG than other parts of the community. Do you really want to go down that road? |
|
The document shepherd writeup is not about IESG interest. This is about gathering the required information to ease the review process for a set of very busy people. |
|
@larseggert I'd like an answer from the IESG on my proposal above. Thanks. |
Please email them? I am about to head out on vacation. Thanks! |
|
LGTM |
Codecov Report
@@ Coverage Diff @@
## main #4042 +/- ##
==========================================
- Coverage 88.21% 88.21% -0.01%
==========================================
Files 295 295
Lines 39164 39169 +5
==========================================
+ Hits 34548 34552 +4
- Misses 4616 4617 +1
Continue to review full report at Codecov.
|
| {# Keep in sync with https://github.com/ietf-chairs/chairs.ietf.org/blob/main/documents/qa-style-writeup-template.md #}{% if doc.stream %}{% if doc.stream.slug == 'ietf' %}# Document Shepherd Write-Up | ||
|
|
||
| *This version is dated 8 April 2022.* | ||
| *This version is dated 1 June 2022.* |
There was a problem hiding this comment.
Confirm whether this should be updated to sometime around 4 Jul?
8 participants
Leaving this as a draft PR for now, so that further community feedback can be accumulated.