diff --git a/docs/contributing/reviewable-prs.md b/docs/contributing/reviewable-prs.md index 5fc81bb01d..2d93d0bc99 100644 --- a/docs/contributing/reviewable-prs.md +++ b/docs/contributing/reviewable-prs.md @@ -82,7 +82,7 @@ helpful for writing clear and thorough pull request comments: - For [screenshots or screencasts][screenshots-gifs] of changes, putting them in details/summary tags reduces visual clutter and scroll length of pull request comments. This is especially - useful when you have various screenshots and/or screencasts to + useful when you have several screenshots and/or screencasts to include in your comment as you can put each image, or group of images, in separate details/summary tags. @@ -96,8 +96,8 @@ helpful for writing clear and thorough pull request comments: - For before and after images or videos of changes, using GithHub's table syntax renders them side-by-side for quick and clear comparison. - While this this works well for narrow or small images, it can be hard - to see details in large, full screen images and videos in this format. + While this works well for narrow or small images, it can be hard to + see details in large, full screen images and videos in this format. Note that you can put the table syntax inside the details/summary tags described above as well. diff --git a/docs/git/pull-requests.md b/docs/git/pull-requests.md index a5e577068d..8935999a68 100644 --- a/docs/git/pull-requests.md +++ b/docs/git/pull-requests.md @@ -116,17 +116,17 @@ branch to your fork, you will see a **Compare & pull request** button. A pull request template will open with some information pre-filled in. Provide (or update) the title for your pull request and write a first comment. -If your pull request has an effect on the visuals of a component, you will want -to include a screenshot of this change or a GIF/screencast of the interaction in -your first comment. You can find a list of tools you can use for this -[here][screenshots-gifs]. +If your pull request makes UI changes, always include one or more still +screenshots to demonstrate your changes. If it seems helpful, add a screen +capture of the new functionality as well. You can find a list of tools you can +use for this [here][screenshots-gifs]. See the documentation for creating [reviewable pull requests][reviewable-prs] for more guidance and tips when writing pull request comments. If the repository has a self-review checklist in the pull request template, make sure that all the relevant points have been addressed before submitting it. -When ready, click the **Create pull request** to submit the pull request. +When ready, click the **Create pull request** button to submit the pull request. Remember to mark your pull request as a [draft][github-help-draft-pr] if it is a work-in-progress.