One of the absolute joys of working from home is my morning ritual with Jenny and our dogs. I’m the first one up, I tend to all the initial dog things. Taking them outside to relieve themselves. Feeding them breakfast.
I brew up coffee and sometimes do the dishes, maybe some exercise. An hour or so later, Jenny comes downstairs with the dogs so eager to see her.
Jenny grabs a coffee mug, heads to her seat across from me in our living room. She sits down and immediately Lacey, one of our border collies, jumps on her lap and begins the morning cuddles.
We’ll sip coffee, go for a walk, play with the dogs, all while chatting about anything, everything, and/or nothing.
Paying Attention to Jagged Edges
One of the topics that tends to come up is customer experience. Moments where we experienced good or bad customer experience. We celebrate the good and lament the bad while looking at both to see what lessons we can learn. Jenny owns Soapy Gnome 📖, so the customer service experience is always at the front of her mind.
, I shared with her that I was looking at some code that would cause both a bad end-user experience and create an internal error message that was unhelpful in triaging the problem. Ultimately creating undo toil and frustration.
In that moment Jenny asked, “What if each time you encountered code such as this you noted it? You could then blog about it, or publish a book on these things, or share them with your team.”
Almost immediately my brain said, “Hey that’s a really good idea. You already wrote a function that does some of the heavy lifting. You could modify that code to help with the capture and organization.”
And I leapt into writing up what this might look like.
Penciling in an Idea
The aforementioned function is a different take on jf/capture-region-contents-with-metadata.
Below is the user story I wrote up. Using the Gherkin syntax.
Given an active region (or line) in the current buffer
And a configured target file
When I execute the “capture” command
Then the capture will write to the target file
a section that “notes” the active region
What does that section look like?
* Subject :org:repo:
:PROPERTIES:
:PROJECT: https://github.com/org/repo/
:END:
** Context
# What brought me to this neighborhood? Introduce the part of the story that
# lead me to the code.
** Code
:PROPERTIES:
:LOCAL_PATH: [[file:~/git/repo/path/to/file]]
:END:
# BEGIN “repeatable” region;
#
# I want an optional parameter to append this region with a header so I can have
# the local file metadata for each of the regions.
#+begin_marginnote
See (remote) [[https://domain.com/org/repo/path/to/file]] for context.
#+end_marginnote
#+begin_src language
The code
#+end_src
# END “repeatable” region
** Discussion
# Why am I singling out this code? What am I seeing as the problem?
** Refactoring
# This is for later revisitation. But with the above clues, hopefully things are in good shape.
One thing I want to further explore, before I dive into implementation, is how I might see the note I just wrote as an annotation of the code. That is, while I’m looking at the code-base, when I’m in a file that has one of these sections, I would see some indicator that allowed me to jump to those annotations.
Why? So I can fill out the Refactoring section.
Conclusion
In years past, the above question and proposal would’ve felt daunting. In part because I hadn’t spent much time configuring and extending my text editors. But with Emacs 📖 the above functionality seems like it will be quick to make; perhaps as simple as a capture template for Org-Mode 📖.
This again speaks to the virtuous cycle I’ve experienced in both sharpening my tools (e.g. extending Emacs) and using Emacs for almost all of my writing: code, prose, poetry, blog posts, time sheet entries, and most anything else.
Now to prioritize the time to hack on this. And see what comes. After all, if I make it easy to draw attention to points of refactor, I’m making it easier for me to share the years of learning and knowledge I’ve accumulated in my career as a software developer.
Plus, I can once again hack on Emacs.