-
Notifications
You must be signed in to change notification settings - Fork 26
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Reorganize the Explainer Explainer, take 2 #57
Conversation
I've tried to make this more readable and I've also included a new item on making explainers a markdown file.
Co-authored-by: Lea Verou <[email protected]>
…plainer-explainer This abandons the "dependencies" addition from w3ctag#40.
* Incorporate the comments from the PR review. * Avoid adding content in the same PR that reorganizes the existing content. * Avoid gratuitous changes to existing text, especially when the diff can match up the original text. * Put the Key Components in the same order as the template, and take non-components out of that ordered list. * Use more structure than just an ordered list in the Tips section.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
it looks good to me - I suggest we merge this and them address the additional issues you've pointed out in a separate PR
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this is a great re-write, thanks for working on it!
|
||
As your work progresses, the explainer can help facilitate multi-stakeholder discussion and consensus-building by making clear: | ||
1. Discussion Venues: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there some reason to put this first?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's been first in the template, and because it tends to be really short, that probably makes sense. Then it seemed weird to have this list be in a different order than the template, even though that takes it out of being ordered by importance. But I'm happy to reorder if you think this item makes more sense elsewhere in the list.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's merge this! I'm looking forward to future improvements that build on this.
This is based on @torgo's #39, with the following significant changes:
I didn't take a couple comments from the original review, mostly because they're additions that we should discuss in a dedicated PR:
The template also needs some updates to match this. Since it's already out of date, let's align on this PR, and then I'll send another one to improve the template.