Update GitHub Skills format for accessibility #408

heiskr · 2023-05-25T18:03:46Z

In a recent accessibility audit, it was determined there was no way to use <details>/<summary> in an accessible way, and we didn't want to completely hide all step content from learners. Updates the course format to split out the steps into separate step files, replaces README content after completion of a step.

To test the course, please test the course directly at https://github.com/skills-dev/introduction-to-github

There's an order of operations hitch here with the update-step workflow, that is temporarily set to the skills-dev org for now. If we decide to move forward, we'll need to update skills/action-update-step first, then edit the fork to use skills/action-update-step@v2, then this will be in a mergeable state.

heiskr · 2023-05-25T18:05:56Z

README.md

@@ -46,7 +49,7 @@ People use GitHub to build some of the most advanced technologies in the world.
 }).toString()
 -->

-[![start-course](https://user-images.githubusercontent.com/1221423/235727646-4a590299-ffe5-480d-8cd5-8194ea184546.svg)](https://github.com/new?template_owner=skills&template_name=introduction-to-github&owner=%40me&name=skills-introduction-to-github&description=My+clone+repository&visibility=public)
+[![start-course](https://user-images.githubusercontent.com/1221423/235727646-4a590299-ffe5-480d-8cd5-8194ea184546.svg)](https://github.com/new?template_owner=skills-dev&template_name=introduction-to-github&owner=%40me&name=skills-introduction-to-github&description=My+clone+repository&visibility=public)


Note, temporary change, will revert this line before merge.

heiskr · 2023-05-25T18:48:19Z

.github/workflows/0-welcome.yml

+
+      # In README.md, switch step 0 for step 1.
+      - name: Update to step 1
+        uses: skills-dev/action-update-step@main


Update these to skills/action-update-step@v2 after update skills/action-update-step ships

ethanpalm

From a content strategy/design perspective, this looks like a good way to present the lesson. I made a few small suggestions in the steps, but no major changes.

I didn't review the files in workflows, but I tested the course and it all worked for me 🎉

.github/steps/3-open-a-pull-request.md

ethanpalm · 2023-05-25T19:20:42Z

.github/steps/1-create-a-branch.md

+   The branch will automatically switch to the one you have just created.
+   The **main** branch drop-down bar will reflect your new branch and display the new branch name.
+
+6. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.


Do you think it would be helpful to send people to https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions instead of the Actions landing page? It's a pretty dense article, but maybe fits the need for why someone would click the link.

Hehe the first sentence "GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform" which isn't what Skills is using it for. More broadly its event hooks + compute 🤷🏼 https://docs.github.com/en/actions/using-workflows/about-workflows A little weird but the content is similar and lines up with Skills case more 🤷🏼

That article looks like a better fit, but I think it would also be fine to leave it as the landing page and let people explore.

No matter which article you go to, if you're brand new to GitHub and end up in the Actions docs you're probably going to 🤯

ethanpalm · 2023-05-25T19:21:38Z

.github/steps/4-merge-your-pull-request.md

+
+**What is a merge?**: A _[merge](https://docs.github.com/en/get-started/quickstart/github-glossary#merge)_ adds the changes in your pull request and branch into the `main` branch. For more information about merges, see "[Merging a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request)."
+
+As noted in the previous step, you may have seen evidence of GitHub Actions running which automatically progresses your instructions to the next step. You'll have to wait for it to finish before you can merge your pull request. It will be ready when the merge pull request button is green.


when the merge pull request button is green

Since we're making these updates with accessibility in mind, is there a non-visual signal that a PR is ready to merge?

This is a throwback to how we used to say it during in-person classes (which is the origins of Learning Lab and now Skills). I'm a proponent of changing it for better accessibility!

I'll open an internal issue for an accessibility content review of the courses, and link to this as an example.

ethanpalm · 2023-05-25T19:22:10Z

.github/steps/4-merge-your-pull-request.md

+
+1. Click **Merge pull request**.
+2. Click **Confirm merge**.
+3. Once your branch has been merged, you don't need it anymore. To delete this branch, click **Delete branch**.


I think this might happen automatically by default, but I'm not 100% sure if that's just how my settings are configured.

It's configured per-repo. Although the template does have auto-delete of the branches turned on, the repo created for me (as the user) did not. I'm not sure if that can be configured for them.

ethanpalm · 2023-05-25T19:23:26Z

.github/steps/X-finish.md

+2. Create a file named `README.md` in its root. The "root" means not inside any folder in your repository.
+3. Edit the contents of the `README.md` file.
+4. If you created a new branch for your file, open and merge a pull request on your branch.
+5. Lastly, we'd love to hear what you thought of this course [in our discussion board](https://github.com/skills/.github/discussions).


Suggested change

5. Lastly, we'd love to hear what you thought of this course [in our discussion board](https://github.com/skills/.github/discussions).

5. Lastly, we'd love to hear what you thought of this course [in our discussion board](https://github.com/orgs/skills/discussions/200).

Maybe we would link specifically to this discussion

This is good, I think it just adds to content maintenance overhead as we may eventually not want to use that discussion anymore. But I'm still a proponent of linking to the proper place - currently the discussions are unorganized and self-serve it seems?

If we do this I suggest creating an official discussion, or better yet a Category, and probably a conversation about who looks after these discussions (or maybe that already exists and I'm just not aware).

Edit: clarify what I meant about discussions.

I'll open a separate internal issue about discussion organization.

hectorsector

Non blocking suggestion - especially now that we have multiple files, it might make it easier to also provide some error handling/troubleshooting. For example, I purposefully added a file to the wrong branch.

Edit: forgot to say, I tested the course and reviewed the workflows. Looks good to me!

Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>

.github/steps/2-commit-a-file.md

heiskr · 2023-05-25T22:23:54Z

Non blocking suggestion - especially now that we have multiple files, it might make it easier to also provide some error handling/troubleshooting. For example, I purposefully added a file to the wrong branch.

It's a good idea, I think starting with a test case in the Action repo would be good. Created: skills/action-update-step#12

Co-authored-by: Courtney Wilson <77312589+cmwilson21@users.noreply.github.com>

.github/steps/2-commit-a-file.md

cmwilson21

Thanks for all the work that went into this! I tested it, too, and it works great!

Co-authored-by: Courtney Wilson <77312589+cmwilson21@users.noreply.github.com>

joeoak

Also followed the course without issue ✨

My only qualm is the wait between steps. I found myself hitting refresh a few times before the next step appeared. I imagine there's not much we can do here, but is there any way to indicate that the action is in progress? Otherwise, I think the "20 second wait" message at the end of each step is clear 👍

sinsukehlab · 2023-05-29T03:58:29Z

I have tested the @skills-dev course.
It works pretty well, but Step 0 workflow runs twice on the initial push to main with one success and one error.
Similar issue: skills/connect-the-dots#32

Gideonkipyegon · 2023-05-30T10:35:32Z

amazing work

heiskr · 2023-05-30T14:49:48Z

Step 0 workflow runs twice on the initial push to main with

I'll open an internal issue to investigate.

…github

heiskr added 4 commits May 25, 2023 09:29

Update course format for accessibility

11b8389

Use header/footer

7918034

Add ref to uses

1420e0e

Temporarily add -dev to org name

49ec579

heiskr requested review from hectorsector, joeoak, ethanpalm and cmwilson21 May 25, 2023 18:04

Rename step 0 to welcome from start

cbb7162

heiskr commented May 25, 2023

View reviewed changes

heiskr mentioned this pull request May 25, 2023

BREAKING CHANGE: Use body replacement instead of details/summary or HTML comments skills/action-update-step#11

Merged

heiskr requested a review from chadfawcett May 25, 2023 18:08

heiskr commented May 25, 2023

View reviewed changes

ethanpalm approved these changes May 25, 2023

View reviewed changes

hectorsector approved these changes May 25, 2023

View reviewed changes

Update .github/steps/3-open-a-pull-request.md

bacbb2c

Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>

cmwilson21 reviewed May 25, 2023

View reviewed changes

.github/steps/2-commit-a-file.md Outdated Show resolved Hide resolved

Update .github/steps/2-commit-a-file.md

86fbea2

Co-authored-by: Courtney Wilson <77312589+cmwilson21@users.noreply.github.com>

cmwilson21 reviewed May 25, 2023

View reviewed changes

.github/steps/2-commit-a-file.md Outdated Show resolved Hide resolved

cmwilson21 reviewed May 25, 2023

View reviewed changes

.github/steps/2-commit-a-file.md Outdated Show resolved Hide resolved

cmwilson21 approved these changes May 25, 2023

View reviewed changes

heiskr and others added 3 commits May 25, 2023 16:57

Add files via upload

1d5988a

Update .github/steps/2-commit-a-file.md

ae7da63

Co-authored-by: Courtney Wilson <77312589+cmwilson21@users.noreply.github.com>

Update .github/steps/2-commit-a-file.md

029cecc

Co-authored-by: Courtney Wilson <77312589+cmwilson21@users.noreply.github.com>

This comment was marked as spam.

Sign in to view

joeoak approved these changes May 26, 2023

View reviewed changes

This comment was marked as duplicate.

Sign in to view

heiskr added 2 commits May 30, 2023 07:51

Preship reversions

acd833b

Merge branch 'main' of https://github.com/skills-dev/introduction-to-…

07e9f33

…github

heiskr merged commit bc2fa49 into skills:main May 30, 2023

This comment was marked as spam.

Sign in to view

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update GitHub Skills format for accessibility #408

Update GitHub Skills format for accessibility #408

heiskr commented May 25, 2023 •

edited

Loading

heiskr May 25, 2023

heiskr May 25, 2023 •

edited

Loading

ethanpalm left a comment

ethanpalm May 25, 2023

heiskr May 25, 2023

ethanpalm May 25, 2023

ethanpalm May 25, 2023

hectorsector May 25, 2023

heiskr May 25, 2023

ethanpalm May 25, 2023

hectorsector May 25, 2023

ethanpalm May 25, 2023

hectorsector May 25, 2023 •

edited

Loading

heiskr May 25, 2023

hectorsector left a comment •

edited

Loading

heiskr commented May 25, 2023

cmwilson21 left a comment

This comment was marked as spam.

joeoak left a comment

This comment was marked as duplicate.

sinsukehlab commented May 29, 2023 •

edited

Loading

Gideonkipyegon commented May 30, 2023

heiskr commented May 30, 2023

This comment was marked as spam.


		What is a merge?: A _[merge](https://docs.github.com/en/get-started/quickstart/github-glossary#merge)_ adds the changes in your pull request and branch into the `main` branch. For more information about merges, see "[Merging a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request)."

		As noted in the previous step, you may have seen evidence of GitHub Actions running which automatically progresses your instructions to the next step. You'll have to wait for it to finish before you can merge your pull request. It will be ready when the merge pull request button is green.

	5. Lastly, we'd love to hear what you thought of this course [in our discussion board](https://github.com/skills/.github/discussions).
	5. Lastly, we'd love to hear what you thought of this course [in our discussion board](https://github.com/orgs/skills/discussions/200).

Update GitHub Skills format for accessibility #408

Update GitHub Skills format for accessibility #408

Conversation

heiskr commented May 25, 2023 • edited Loading

Choose a reason for hiding this comment

heiskr May 25, 2023 • edited Loading

Choose a reason for hiding this comment

ethanpalm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hectorsector May 25, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hectorsector left a comment • edited Loading

Choose a reason for hiding this comment

heiskr commented May 25, 2023

cmwilson21 left a comment

Choose a reason for hiding this comment

This comment was marked as spam.

joeoak left a comment

Choose a reason for hiding this comment

This comment was marked as duplicate.

sinsukehlab commented May 29, 2023 • edited Loading

Gideonkipyegon commented May 30, 2023

heiskr commented May 30, 2023

This comment was marked as spam.

heiskr commented May 25, 2023 •

edited

Loading

heiskr May 25, 2023 •

edited

Loading

hectorsector May 25, 2023 •

edited

Loading

hectorsector left a comment •

edited

Loading

sinsukehlab commented May 29, 2023 •

edited

Loading