[docs] Introduce video introduction #18014
Conversation
Compared to the existing text, a visual introduction may be more approachable for some potential contributors. The documentation currently recommends a recording of a lecture, but that video is too long and technical to reach those whose commitment to the project is uncertain. Introduce a new video designed for first-time contributors. Include a transcript so that visitors who are not able to experience the video may still benefit from its content. Relocate the link to the lecture to the appendix.
| A hand places a cutout representing a stack of papers on the top-center of the | ||
| sheet and draws an arrow from that cutout to the cutout of the browser window. | ||
|
|
||
| > To do verify their work, the browser maintainers rely on the third part of |
There was a problem hiding this comment.
| > To do verify their work, the browser maintainers rely on the third part of | |
| > To verify their work, the browser maintainers rely on the third part of |
| > There, were can navigate among all the tests for all the different web | ||
| > technologies. | ||
| > | ||
| > Let's take a look at a typical test. |
There was a problem hiding this comment.
Might be good to include typing in a search (e.g. fetch)
| `https://web-platform-tests.org` is entered into the location bar, and the | ||
| browser loads the page. | ||
|
|
||
| > Other types of tests include "reftests" (for verifying the visual rendering |
There was a problem hiding this comment.
Maybe move to a reftest on wpt.fyi for visual effect here?
There was a problem hiding this comment.
Good idea! I'm suggesting more "view source" stuff to demonstrate the relation between test and reference. I'll add some more explanation according to what feels natural in the time it takes to perform this action.
|
Thanks for the review, @lukebjerring! I've selected some moderately interesting examples for reference tests and manual tests, but there are probably better ones out there. Do you have any favorites? |
| @@ -118,12 +118,24 @@ source of the failing test. | |||
| > instance has a custom JavaScript iterator method. That's a strange edge case, | |||
| > but it's important for browsers to agree on every detail! | |||
|
|
|||
| `http://web-platform-tests.live/css/css-transforms/transform-transformed-tr-contains-fixed-position.html` | |||
There was a problem hiding this comment.
https://wpt.fyi/results/css/css-transforms/transform-transformed-tr-contains-fixed-position.html highlights the "reference vs actual" concept a little more here.
| > Hello, and welcome to the Web Platform Tests! | ||
| > | ||
| > The goal of this project is to ensure that all web browsers present websites | ||
| > in exactly the way the websites' authors intended. |
There was a problem hiding this comment.
| > in exactly the way the websites' authors intended. | |
| > in exactly the same way. |
(I think shortening this makes it easier to understand; the duplication of "websites" makes this slightly awkward IMO.)
|
@sideshowbarker @lukebjerring @gsnedders The video's ready! As expected, the actual timing of the action informed the spoken word a bit. The video includes a more substantial description of reftests and manual tests than originally proposed. What do you think? |
|
Here's a direct link: https://www.youtube.com/watch?v=SMdEIRcolSY |
|
Here's a patch for the Firefox bug that this video demonstrates https://bugzilla.mozilla.org/show_bug.cgi?id=1567323 |
|
Some folks let me know that the volume of the narration is too low from 2:44 until 4:08. Creating a new version takes a little time, so I'm going to hold off on fixing that while waiting for more feedback. @lukebjerring Are you purchasing wpt.live to replace web-platform-tests.live? If so, I should re-record the parts that reference the latter. |
|
Yes, @foolip already did I think? and wpt.reviews is also the plan, just jumping through bureaucracy hoops to make that happen! |
|
Yep, we've had wpt.live and not-wpt.live since February. |
|
@foolip @gsnedders @sideshowbarker I've re-recorded the audio and updated the reference to wpt.live. This should be good to go! |
|
That's great, @foolip! Do you think we should seek out approval from anyone in particular? |
|
@jugglinmike not really, plenty of people were poked and two have explicitly approved, so I'll just go ahead and merge this. When you've put the project files and highest quality render somewhere, can you link to them in a comment or something, in case we don't want to use YouTube at some point in the future? |
|
You got it Video: https://archive.org/details/wpt-intro-video-2019 Assets: https://archive.org/details/wpt-intro-video-2019-assets |
|
Excellent, thank you! |
Compared to the existing text, a visual introduction may be more
approachable for some potential contributors. The documentation
currently recommends a recording of a lecture, but that video is too
long and technical to reach those whose commitment to the project is
uncertain.
Introduce a new video designed for first-time contributors. Include a
transcript so that visitors who are not able to experience the video may
still benefit from its content. Relocate the link to the lecture to the
appendix.
Like gh-17811 and gh-17894, this was inspired by conversations with @fantasai, @frivoal, @lmccart, @ericholscher, @jihyerish, and @chrisdavidmills and the experience of the Django project maintainers.
This work-in-progress pull request currently only contains a transcript; we haven't made the video yet. My hope is that this will make it easier to design the content collaboratively. Once those involved are satisfied, I'll follow up by producing the actual recording.
Does this hit all the most important points for a first-time contributor? Is there anything we should add? Anything we should remove?