#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-workshop 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. Ideally, this profile picture matches the one you’ve used for your other online portfolios (e.g. your personal website, LinkedIn, etc.). 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.