#1 Original Ocotcat. See the full collection of octocats, or create your own
Anticipated deliverable(s)
By the end of today’s workshop, you should have:
- a polished and informative README added to one (or more) of your past MEDS homework assignments repositories
- a thoughtfully-curated GitHub landing page, inluding a profile picture and bio, pinned repositories, and a profile README that welcomes visitors and showcases your interests / work
Learning objectives
By the end of today’s workshop, you should be able to:
- write clear, informative READMEs that help others understand, navigate, and use the contents of yhour GitHub repositories or software products
- curate your GitHub profile to showcase your skills, interests, accomplishments, and personality(!)
- enhance the accessibility of your GitHub content by applying web accessibilty best practices when writing READMEs
Pre-class Prep
Please be sure to complete the following before class:
A. Watch Abigail Haddad’s posit::conf(2024) talk, GitHub: How To Tell Your Professional Story (15 min)
Abigail Haddad is a Machine Learning Engineer at the US Department of Homeland Security. Her posit::conf(2024) talk, titled, GitHub: How To Tell Your Professional Story is an excellent primer for thinking about GitHub as a professional portfolio.
B. Choose a GitHub repo from a past homework assignment
README files are used to provide essential information about software projects. We’ll practice writing effective READMEs, using a past MEDS homework assignment as an example. Choose one of the GitHub repositories from the list of past homework assignments, below:
TBD
C. Draft up text to add to your GitHub profile README
A GitHub profile README is a special README that is displayed on your profile’s landing page (e.g. see mine). A well-crafted profile README not only welcomes visitors to your page, but can also help you stand out to potential collaborators or employers. It’s helpful to include a short bio and highlight some current projects / interests.
Consider what content you might want to include in your GitHub profile README (and remember to refer back to your branding guide!). Take a look at a few examples for inspiration, then draft up some text / images / etc. in a Google Doc (or other easily accessible location) to refer to during class (it’s okay if this is just a first pass – you can continue to iterate!).
- Allison Horst
- Alex Phillips
- Silvia Canelón
- Crystal Lewis
- Marine Kochuten
- Awesome GitHub Profile READMEs (a collection of great profile READMEs)
D. Have a profile picture handy
We’ll update our GitHub profile picture during class, if you haven’t done so already. Save it to an easy-to-find place (e.g your desktop).
Workshop Materials
| Content Type | Materials | Notes |
|---|---|---|
| Instructional document | MEDS README Guidelines | The “official” guidelines, assembed by MEDS instructors. You’ll be asked to refer back to these throughout your time in MEDS! |
| Slides | MEDS README Guidelines | A slightly-more engaging version of the README guidelines (above) for teaching |
| Slides | GitHub Glowup | NA |
What should I continue working on?
- Put any finishing touches on your homework repo’s README. If you’re feeling particularly inspired, you can also add / update READMEs for your other homework (or even personal) repositories as well.
- Complete your GitHub profile bio and README. Remember, your README should evolve with you. Consider revisiting it a few times throughout the year to make updates as you start (and complete) projects. You can add / switch out your pinned repos as well.