mcclellangg.com

Workflow Workshop with GitHub Issues and Gists

May 20, 2025

How the discovery and implementation of simple GitHub features have improved my organizational workflows.

Over recent months, I've started to expand my GitHub usage, and have found some helpful features. Previously, it was little more than free cloud storage for my code repos. However, as I have shifted more of my projects to it, I am realizing there are many simple but powerful features I never thought to use.

GitHub Issues and GitHub Gists are the most useful features I have discovered so far. I use them both almost daily.

Issues

Depending on the scale of certain projects, I keep related notes (to-dos, next steps, design ideas) in one (if not more) place(s) per project:

  • Manually in my daily notebook
  • A Markdown file in my project named either notes.md or dev_log.md
  • Within the docstrings of scripts, or as comments (yucky, I know)
  • A separate note in Obsidian (a practice I quickly abandoned due to its inefficiency)

An unfortunate theme started to develop where I would come back to projects I hadn't worked on in a while expecting my notes to be in one place, only to find them in a completely different state, or sometimes not find them at all. Not desirable.

But then one day I discovered Issues! I got the idea of using issues from Eric Matthes, who mentions this specific Issue - Parking Lot in his article re-naming things is hard.

Until reading that article, I never thought to use GitHub in my personal projects in a manner similar to Confluence/JIRA tickets. Since then, issues have become a staple for helping me keep my projects organized and on track!

Gists

Oftentimes when programming, I come up against something I'd prefer to be more familiar with, but taking a detour to investigate it would distract me from solving the problem at hand. Until I discovered Gists, I would usually handle this situation by some combination of the following methods:

  • Interrupt the flow with a side quest to quench my thirst for knowledge (a bad habit I am working to break)
  • Jot a memo in my daily notebook to revisit later (or, more often, never)
  • Create some hasty documentation to add to a growing collection of disparate digital notes (primarily in various knowledge base Git repos, or in Obsidian)

Writing in my notebook and revisiting was great when I remembered, but I rarely stuck to a consistent method to convert these notes digitally. As a result, notes were scattered across several Git repos, making the system unmaintainable.

Luckily, though, I came across this older Hacker News thread and started using Gists for TILs. Now when I come across something I want to learn more about, I use the following workflow:

  • Jot a memo in my notebook, and label it TIL (in colored ink)
  • Dedicate time at the end of the day to review any outstanding TILs and convert them into gists

Gists are a fantastic format because they have all the benefits of a GitHub repo without the overhead of figuring out how it's organized or what it might become. You can focus on a single topic and save it as a gist.

Previously I shied away from including any multi-line code here because formatting was a nightmare. But now it is as simple as creating a gist and sharing an embed! I came across this gist when working on a previous project:

Conclusion

I am constantly amazed at how much I learn by working with or by seeing how other programmers work. So far, it continues to lead to my most profound moments of growth and takes me places I never expected to go. Strangely enough, the human element is one of the things I love most about programming. I hope by sharing these insights (small as they may be) that others will benefit from them as I have, and be encouraged to do the same.

Stay curious!

Resources