Published 2025-02-17
tag(s): #emacs #programming
A few weeks ago I completely overhauled the configuration of my keyboard[1]. I keep notes of my setup, with screenshots and text snippets explaining why one thing or the other.
It all started because I figured it would be nice to keep screenshots for when I don't have
installed Bazecor, the software to configure the Dygma Raise. I ended up installing that in
the work computers anyway.
But I was still referring to the screenshots when I over-modified a layer (in the early days)
and needed to go back to previous state. So I added some notes on each change, and that point
I figured it was better to just put it in a nicely formatted file with the rest of the
dotfiles, in a repository.
And even just now, as I updated the notes to reflect the current state, the process of capturing the screens and explaining the changes helped me find inconsistencies and little improvements that I hadn't noticed before. Which in turn prompted me to write this post.
I credit the attitude about documenting my own config to, of course, Emacs. And Lisps in
general.[2]
Since I started programming Elisp (and then CL) having detailed documentation became second
nature, and so many times said documentation was critical when figuring out an issue
in the code. In particular, but not exclusively, when said issue is found long after writing
the offending code.
Of course, I am not discovering anything new here. Actually, referencing a habit from Lisps dates this idea as something ancient 🤣 but that doesn't mean it is not relevant or worth celebrating. Or that we don't need to reinforce the habit, and try to spread it.
Documenting your own configuration is not an act of self-importance, but of self-care. And the same applies to the code you put out there. The act of writing docs will help you revisit your initial assumptions and shed a light in your thought process. And reading those docs even after just a few weeks can be quite a revelation...