lyall.co

Prove You Care (Write the Docs)

2026-08-02T00:00:00+00:00

For better or worse, other-than-human-authored code looks here to stay. Personally, I'm okay using and even creating</a> software</a> whose code was written by LLMs. Programming languages, by their very nature, are intended for computer consumption.1</a> So there's a certain level of appositeness in code written for and by computers.

Moreover, code can be measured and tested objectively. You can define an arbitrary target—functionality, performance, correctness—and generally determine whether a program meets it or not.2</a> Code does have characteristics that are harder to measure—beauty, elegance, style—but those are generally secondary to whether the program performs correctly.

Documentation inverts this. It has some attributes that can be measured more easily, such as coverage or being up to date. But the most important part of documentation is communicating ideas effectively, and that's a lot harder to measure.

Documentation is also still intended for human consumption. Maybe a function docstring can get by purely stating the facts, but a project README needs to provide context, build trust, and educate. All while guessing the reader's background and state of mind. Today's frontier models can produce passable writing, but still will veer into dense, jargon-filled tangents at a moment's notice, and they do a poor job of understanding a potential reader's mindset and providing appropriate context.

When an LLM writes your documentation wholesale, you're signaling that you don't care about the humans on the other end. You don't care about communicating ideas to them effectively. You don't value their time and effort.

If you want some human engagement, put in some human effort.

Programming languages are, of course, also intended for human consumption. But that's more a byproduct of necessity during program creation rather than its inherent purpose. ↩</a> </li>

It's not always easy though! ↩</a> </li> </ol> </section>

Careful Communication

2025-08-17T00:00:00+00:00

I got a massage recently. And as I was lying there and relaxing, my attention came to the music softly playing in the background. It was R&B-flavored, chill, slightly lo-fi and distinctly generic.
With each song coming and going, and with nothing else to focus on, I start noticing some strange patterns. The songs are similar enough to be from a single album, but the vocalists sound like a different person on each track. Some songs suddenly go from featuring zero guitar to guitar solo. Then as quickly as the guitar solo came it goes and the whole song starts fades to a close. The lyrics are very same-y, with small portions even repeated verbatim across different tracks.
But overall the music was not unpleasant. Frankly I was glad that the place wasn't playing the same ten C-tier pop song covers that they usually play on an endless loop.
Not unpleasant as it was, I couldn't shake the feeling of a distinct lack of care in the creation of the music. Whoever made it didn't care that the lyrics were repeated from one track to the next. They didn't care if a guitar solo didn't fit with the rest of the song. They did care about the general vibe and quantity, however.
On my way out I Shazam’d the currently playing track, only to find that the artist was "AI MUSIC MATRIX". Who, from a brief search, appears to be a Japanese guy making this stuff with a combination of ChatGPT, Claude and Suno, and apparently quite successfully based on his engagement stats.1</a> Maybe you saw it coming, but I was somewhat surprised to actually encounter AI music in the wild.
The experience made me reflect on care—specifically on what we choose to care about. Choosing to care about music's vibe and quantity over artistic expression or craftsmanship isn't an inherently invalid or wrong choice. But it is a selfish one, I think.
Creation is the most powerful tool for communication that we have. Music, writing, art, software… it all communicates something to those that experience it. If you devote your time and energy and self into something—a song, a piece of writing, an app—that artifact forever communicates that you care. You cared enough about the people who experience and interact with it in the future to put in the dedication to create it.
So what do you communicate when you have AI write your email, write your app, write your song? That you don’t care. You don’t care about the person on the other end to put the time in yourself. You do care about yourself, about saving your own time and energy. But not about them.
AI is undoubtedly a powerful tool, but to what end? Do we use it as a tool of convenience to enable our laziest and most selfish impulses? Or do we use it to achieve new heights of craftsmanship, of expression, of care for our fellow human beings?

Please don't take this as an indictment of this artist in particular. Maybe AI has unlocked a new level of self-expression that wasn't accessible to them before. I simply share the anecdote as the catalyst for making me think about the topic. ↩</a> </li> </ol> </section>

Japan Payments Musings

2022-07-22T00:00:00+00:00

I've been living in Tokyo for almost three months now. Combine that with my elementary schooler level Japanese literacy and I've basically become an expert on the Japanese payments landscape. Lack of expertise notwithstanding, here are a few things I've noticed so far that have surprised, delighted and confused me, sometimes all at the same time.

Super Fast git status</code>
2022-06-28T00:00:00+00:00This is a follow up to part one</a>. </div> For a while, git has supported an fsmonitor hook</a> to allow running a process like watchman</a> in the background to, well, watch for changes to files in the repo and report them back to git when they happen instead of git waiting to look for changes all at once after you call the status</code> command (like a sucker). This was great in theory, but I had two problems with it when I tried it. First of all, setting it up was annoying! You had to decide which watchman-like tool to install, write (ok, copy and paste) a git hook to call it correctly and hope that you didn't break anything else along the way. Second of all, and more importantly, it didn't make things any faster! I timed running git status</code> with and without the hook enabled, and never found much of an improvement. This was disappointing as I'd read everywhere how it was supposed to speed things up greatly. However today I stumbled back upon git's fsmonitor settings and found out that a new version of git was released today (2022-06-27)—version 2.37.0—that includes a built in fsmonitor daemon</a>, meaning that watchman and an fsmonitor hook are no longer needed to get the same behavior. I decided to give it a go by updating my git config: git config --global core.fsmonitor true</code></pre> I then ran git status</code> in my very large repo of choice once to get the daemon started, then again and wtf... it returned almost instantly? Doing the usual benchmarking confirmed it, git status</code> now returned just 84ms. Remembering my previous failure to squeeze much performance out of using an fsmonitor, I wondering if this huge improvement was because of it being built in to git or because of something else, so I decided to test the three untracked file modes of git status</code> with and without the fsmonitor enabled. untracked files</th> without fsmonitor</th> with fsmonitor</th></tr></thead> no</code></td> 179ms</td> 45ms</td></tr> normal</code></td> 279ms</td> 84ms</td></tr> all</code></td> 966ms</td> 827ms</td></tr> </tbody></table> If you want a great visual comparison of what this kind of difference in latency looks like, check this out from @Piwai</a>. </blockquote> So it turns out that whatever the all</code> mode is doing under the hood must be cancelling out most of the speed gains from having the fsmonitor enabled, which explains why I never had great results with it in the past, since all</code> was enabled as the default! Try it out and see if it helps in your local mongo repo. Make git status</code> Faster with this One Weird Trick! 2022-06-27T00:00:00+00:00 Many of us toil away in large git repos, spending countless seconds every day waiting for git status</code> to return to us its precious information deep from within the bowels of git tree itself. Much work has gone into git over the years to improve its performance in large repos. By my own measurements, on a fancy new M1 MacBook git status</code> runs in a tolerable but sluggish 960ms at its fastest, but sometimes takes twice as long. For a while I'd known about a way to make git status</code> run quickly for times when you're feeling especially impatient—by telling it to ignore untracked (new to the repo) files with the with the --untracked-files=no</code> flag, or --uno</code> for short. With this flag we only have to wait 190ms for that sweet, sweet output. However, setting this as the default didn't work for me, as I was prone to forgetting that I'd created a new file and forget to add it into a commit, so I was stuck waiting a whole second still. Git supports two other modes for the untracked files flag: normal</code> and all</code>, with normal being the default (surprise!). Curious, I decided to compare the performance of all three modes in a large work repo, and got the following results: git status -uno 190ms git status -unormal 290ms git status -uall 960ms</code></pre> NB: benchmarks performed with hyperfine</code> and don't represent worst case performance due to warmups, etc. </div> I was surprised by two things here. First that normal</code> was only 100ms slower than the speedy no</code> option, and second that the speed of git status -uall</code> was the same as un-flagged git status</code>... hold on, I thought, we're using the slow option as the default?! In this economy?? Yes, it turns out, by default everyone at my company's .gitconfig</code> file contains the following: [status] showUntrackedFiles = all</code></pre> So by deleting the offending line (or changing it to normal</code>), we can reap a 3.3x speed boost to git status</code> without sacrificing knowing if we've got untracked changes to worry about. What exactly is the difference in the output between normal</code> and all</code> though? Like its name implies, all</code> shows all untracked files, with their full paths, while normal will just show the directories containing any changed files but not the files themselves. Sounds like an acceptable tradeoff to me. Tell your friends—together we can take back entire minutes of lost productivity. Bonus tip!</h3> You can claw back another couple milliseconds but really just get pithier status</code> output with the --short</code>/status.short</code> flag/config value. The saga continues in part two</a>. </div>

`Bonus tip!</h3> You can claw back another couple milliseconds but really just get pithier status</code> output with the --short</code>/status.short</code> flag/config value.</p>`
`The saga continues in part two</a>.</p> </div>`

lyall.co

Prove You Care (Write the Docs)

Careful Communication

Japan Payments Musings

Super Fast `git status</code>`

Make `git status</code> Faster with this One Weird Trick!`

untracked files</th>	without</em> fsmonitor</th>	with</em> fsmonitor</th></tr></thead>
`no</code></td>`	179ms</td>	45ms</td></tr>
`normal</code></td>`	279ms</td>	84ms</td></tr>
`all</code></td>`	966ms</td>	827ms</td></tr> </tbody></table> If you want a great visual comparison of what this kind of difference in latency looks like, check this out from @Piwai</a>.</p> </blockquote> So it turns out that whatever the `all</code> mode is doing under the hood must be cancelling out most of the speed gains from having the fsmonitor enabled, which explains why I never had great results with it in the past, since all</code> was enabled as the default!</p>` `Try it out and see if it helps in your local mongo repo.</p>` Make git status</code> Faster with this One Weird Trick! 2022-06-27T00:00:00+00:00 Many of us toil away in large git repos, spending countless seconds every day waiting for git status</code> to return to us its precious information deep from within the bowels of git tree itself.</p> Much work has gone into git over the years to improve its performance in large repos. By my own measurements, on a fancy new M1 MacBook git status</code> runs in a tolerable but sluggish 960ms at its fastest, but sometimes takes twice as long.</p> For a while I'd known about a way to make git status</code> run quickly for times when you're feeling especially impatient—by telling it to ignore untracked (new to the repo) files with the with the --untracked-files=no</code> flag, or --uno</code> for short. With this flag we only have to wait 190ms for that sweet, sweet output. However, setting this as the default didn't work for me, as I was prone to forgetting that I'd created a new file and forget to add it into a commit, so I was stuck waiting a whole second still.</p> Git supports two other modes for the untracked files flag: normal</code> and all</code>, with normal being the default (surprise!).</p> Curious, I decided to compare the performance of all three modes in a large work repo, and got the following results:</p> `git status -uno 190ms</span></span> git status -unormal 290ms</span></span> git status -uall 960ms</span></span></code></pre>` NB: benchmarks performed with `hyperfine</code> and don't represent worst case performance due to warmups, etc.</em></p> </div>` `I was surprised by two things here. First that normal</code> was only 100ms slower than the speedy no</code> option, and second that the speed of git status -uall</code> was the same as un-flagged git status</code>... hold on</em>, I thought, we're using the slow option as the default?! In this economy??</small></em></p>` `Yes, it turns out, by default everyone at my company's .gitconfig</code> file contains the following:</p>` [status]</span></span> showUntrackedFiles = all</span></span></code></pre> So by deleting the offending line (or changing it to normal</code>), we can reap a 3.3x speed boost to git status</code> without sacrificing knowing if we've got untracked changes to worry about.</p> What exactly is the difference in the output between normal</code> and all</code> though? Like its name implies, all</code> shows all untracked files, with their full paths, while normal will just show the directories containing any changed files but not the files themselves. Sounds like an acceptable tradeoff to me.</p> Tell your friends—together we can take back entire minutes of lost productivity.</p> `Bonus tip!</h3> You can claw back another couple milliseconds but really just get pithier status</code> output with the --short</code>/status.short</code> flag/config value.</p>` `The saga continues in part two</a>.</p> </div>`

lyall.co

Prove You Care (Write the Docs)

Careful Communication

Japan Payments Musings

Super Fast git status</code>

Make git status</code> Faster with this One Weird Trick!

Bonus tip!</h3> You can claw back another couple milliseconds but really just get pithier status</code> output with the --short</code>/status.short</code> flag/config value.</p> The saga continues in part two</a>.</p> </div>

Super Fast `git status</code>`

Make `git status</code> Faster with this One Weird Trick!`

`Bonus tip!</h3> You can claw back another couple milliseconds but really just get pithier status</code> output with the --short</code>/status.short</code> flag/config value.</p>`
`The saga continues in part two</a>.</p> </div>`