I recently introduced a requirement gathering template for GitHub issues at work, after finding too many times this step had moved into the main process and impeded my ability to proceed.
The issue was structured in 3 sections:
- Components to be edited, how, and ambiguities (known unknowns, any cognitive dissonance)
- Routines those components fit into
- Original work/analysis
The problem was: this is very structured (a lot like code) and I found it awkward to write in this style in a browser.
After I moved to gh on the command line for pull requests (see part 1 of this series)
it was the natural next step to consider writing issues there too.
It turned out that when you edit issue bodies with gh, it drops you into your editor
(in my case, vim). I'm a seasoned vim user so this made writing issues way faster.
I still wasn't all in at this point, I guess as I had no particular drive to be.
I tried this from the first week of May, until mid-way through the month, the Linear web browser issue interface glitched and edited a couple of paragraphs many dozens of times in seconds flat, leaving me with nonsense:
I was pretty distressed and immediately became focused on retrieving the comment edit
history via the GitHub GraphQL API comments endpoint (it wasn't there, meaning the GitHub frontend
had just shredded my plan of action). I used gh api for this (code).
It was a shock how much this disrupted me: I had been in flow, with a plan of action bubbling up into my conscious awareness. I didn't have it written down anywhere else, so this glitch stopped me in my tracks: the idea evaporated as if I'd simply forgotten.
At this point I vowed I would henceforth only write issues in vim, an editor I trust to handle my work robustly with extremely low (I'd say negligible) failure rate.
These files are stored as temporary files (in /tmp/) which I'm unsure persist upon restart...
but this is rare enough not to be a consideration for me. The more likely event is that
you'd be able to recover after an unexpected terminal exit (vim keeps .swp files of all edited
text files while you edit them meaning everything can be recovered).
The quality jump from doing this was noticeable. It simply feels more 'natural' and nimble
to write high quality issues (especially in structured templates). The gh tool also allows
you to bypass templates and start from a blank issue (which sometimes is itself helpful to keep a
clear idea in mind).