Skip to content
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

Merged
merged 4 commits into from
Jan 21, 2025

Conversation

jyasskin
Copy link
Contributor

@jyasskin jyasskin commented Dec 26, 2024

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.

torgo and others added 4 commits July 11, 2023 15:16
I've tried to make this more readable and I've also included a new item on making explainers a markdown file.
…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.
Copy link
Member

@torgo torgo left a 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

Copy link

@alice alice left a 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:
Copy link

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?

Copy link
Contributor Author

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.

Copy link
Contributor

@hober hober left a 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.

@jyasskin jyasskin merged commit 6d54ae6 into w3ctag:main Jan 21, 2025
@jyasskin jyasskin deleted the revise-explainer-explainer branch January 21, 2025 23:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants