Friends Don't Let Friends…

A brief meditation on personal preferences, told with Python and org mode

One of the online blog posts closest to my heart over the last few years is Friends don't let friends write production software in Python by Julien Voisin. I began my software engineering career with JavaScript projects, then Python coding interviews and Golang projects. At some point I settled primarily on Golang as a general means of doing things across all domains: personal, salaried and contract work. I don't have zero Python experience, but it was near-zero.

More recent work has involved a great deal more Python, and I've become intimately familiar with issues annoying enough to fit well with Voisin's post above. Now I know the pain of accidentally checking if a generator is truthy (which it always is, unless it is None, but that's a distinct and rarer problem than zero results in an underlying comprehended list), or using a boolean and inside a function argument when it should actually be a , between two simple booleans, etc. etc. ad infinitum.

For these and other reasons, I would still not characterize myself as a fan of Python. I fear I possess a sort of fundamental inability to do that; I suspect I'll always find well-managed strictly-typed codebases easier to navigate, more intuitive and more readable. But I do like it a great deal more than I did when I first encountered the article.

As the saying goes: “be careful what you wish for, because on the internet you always find it.“ So too I found an article with the sentiment I had myself, which unduly reinforced it. Now, I could hereafter go down the rabbit hole of explaining that languages are tools, that each is good for its own purposes and none is objectively best; let he who has perfectly implemented linked lists cast the first stone and so on. Instead I present a second example derived from a single Gwern quote, and the immediate impetus for this writing:

Friends don't let friends use heroin or org-mode—are you ever really doing to make back the time it takes to learn & customize org-mode?

This longstanding quote from his Me page articulates a timeless truth: there are tools of limited marginal value that people sink immense time into, far beyond the point of diminishing returns. One need only look to YouTube for an endless trove of productivity gurus who spend far more time discussing their tools than using them—"those who can, do, and those who can't, talk about using Roam1 to organize their reading notes.“ Unfortunately this quote caused me to mostly ignore org-mode and only give it cursory glances for several years. Turns out it's great!

Please excuse me as I very carefully dissect what “great” means here. It's interesting: Gwern is patently correct in all meaningful ways with respect to himself and as a warning to avoid sinking time into a power tool you don't need—a tool configured in plaintext config files rather than a UI, no less, to make matters worse—and yet, it would seem, incorrect from my perspective. This is a truth in multiple quantum states: the sort of keep-away sign that says “if you're a certain sort of person with a very specific use case, don't actually keep away, but seriously you probably ought to keep away.“

Although I do niche things like run Gentoo Linux and keep many of my tasks inside the CLI, I don't endlessly configure what I use. I use mostly-stock Doom Emacs, entirely stock JetBrains IDEs & vim save a 6ish-line config, and lately, it would seem, stock org-mode. Now, considering the keep-away sign I mention above, it seems I would need a very specific, precise use case to make this decision worth it. Often such use cases are hard to describe lest they reveal uncomfortable personal information or get into minutiae to no useful end. At best they're niche and silly. So it's best not to get into it.

My Very Specific, Precise Use Case for Org-Mode

Org-mode is a strange beast. It's a text-based structured system of note-taking, outlining, project planning and personal productivity, it's all but unknown to everyone outside a small orbit of tech nerds and some academics, and it's so extensible that it could be of use to anyone given a sufficient time investment. The word “sufficient” there certainly seems to be doing lots of work, so I should preface this by saying I've made absolutely zero modifications to stock org-mode and I'm not quite sure what I'd even do if I went down that route.

Further, I should say that I, like any reasonable person, am overwhelmed when I type SPC+m or SPC+:org- in my Doom Emacs installation. These keystrokes expose an endless selection of functions that string verbs together, perhaps to infinity; of course you ought to expect as much considering Emacs is over a million lines of code!

I have no interest in any of those. Perhaps it's nice to know that for every strange niche situation I could encounter with org-mode, there's already a tailor-made function for it, but I'm not sure how comforting that really is or what the situation would even be. We're talking about pretty simple text files here.

Simply put, albeit in the fourth paragraph: my use case is that I've long sought a system that gracefully handles both lists-as-lists and lists-as-agendas. In org-mode, the majority of what you do is based on nested bulleted lists with brief tags to denote their purpose, like TODO or PROJ or DONE, like:

* PROJ Write a note about org-mode [0/2]
** TODO Prepare myself to discuss the sacred texts
   SCHEDULED: <2020-10-20 Tue 04:00>
   I estimate this will take 9 hours of meditation. Scheduling early.
** TODO Sit and write, thanking Gaia for the occasion
   DEADLINE: <2020-10-21 Wed 19:00>

And so on. These lists expand like trees and can become arbitrarily complex, and there are various keybindings of some use like CTRL+Return to toggle the state of the item below the cursor between its original state and DONE, or managing scheduled date and deadline for you. I personally have three .org files at time of writing with various sorts of goals, projects, lists and queues in progress or for occasional reference, and it's pretty nifty but not all that different from using a plain text file to organize my affairs.

The game-changer is org-agenda, the one aspect of org-mode that's worth discussing for me because it solved my major use case. In Doom Emacs, if I type the command SPC-o-A-a, I'm greeted with a chronological view of scheduled dates and deadlines for the next week or so, automatically built from all my items that have dates in the plain text:

10 days-agenda (W42-W44):
Saturday   17 October 2020
Sunday     18 October 2020
Monday     19 October 2020 W43
Tuesday    20 October 2020
               1:34...... now - - - - - - - - - - - - - - - - - - - - - - - - -
               8:00...... ----------------
              10:00...... ----------------
  general:    12:00...... Deadline:   TODO Remind REDACTED to call her dentist
              12:00...... ----------------
              14:00...... ----------------
              16:00...... ----------------
              18:00...... ----------------
              20:00...... ----------------
  general:    23:00...... Deadline:   TODO Do a REDACTED WORK THING
  goals:      In  10 d.:  TODO Make sure the REDACTED is second-nature [0%]
  goals:      In  10 d.:  TODO Make a dev roadmap for Nov based on Oct
Wednesday  21 October 2020
Thursday   22 October 2020
  goals:      12:00...... Scheduled:  HOLD Follow up with tattoo artist
Friday     23 October 2020
Saturday   24 October 2020
  goals:      Scheduled:  HOLD Schedule next free session with REDACTED
Sunday     25 October 2020
Monday     26 October 2020 W44
  goals:      Scheduled:  TODO Make a dev roadmap for Nov based on Oct

It's such a simple feature, but very nice because I don't have to worry as much about the organization of my lists themselves; once something has a timestamp, I know it'll show up in that view, and within that view I can hover over any item and hit enter, and Emacs will open the appropriate file and navigate to the item.

There are, of course, other systems that do this, but I appreciate that org-mode offers no further opinionation on the way you should structure anything, is entirely local and based on plain text files, and has at least the potential for extensibility should a certain use case assert itself. This is itself a mixed blessing, and I will neither suggest that it's universally bad nor good. Obviously, some people would sing org-mode's praises by discussing its extensibility, and surely you can modify its base behavior in infinite ways—but then we fall into Gwern's noted trap.

Instead I offer this thesis: org-mode is a legitimate tool worth investigating for oneself, but merely scratching the surface of its functionality is sufficient for almost everyone.

The greater lesson this demonstrates for me is twofold: to take heed of other people's opinions on software but make sure I properly investigate them myself, i.e. the obvious lesson, and to be willing to evaluate complex tools from the perspective of a beginner. I certainly don't have any opinions on how to extend org-mode, how easy or difficult it is, how much time to invest before you become concerned about making it back, etc. As I said, I highly doubt I'll extend it much myself. But it's lazy analysis to dismiss the option out of hand for fear of its complexity, as I have done in the past.

I must say I expected to further emphasize Gwern's warning in this piece, and it's worth noting that it's extremely important advice for popular and niche software alike: the system is a screwdriver and not a chair, a means rather than an end. I can't imagine a demographic more likely than software engineers to get obsessed over the implementation of a system rather than its results. One must carefully examine their priorities before they can make a valid judgment on where to invest valuable time.


Here I risk coming on too strong on the subject. In some sense this is likely a narcissism of small differences: I would much sooner praise someone for using any productivity software at all, but I also (duly, I think) criticize the act of shilling the software rather than the outcomes it's supposed to enable. I leave it to the reader to consider.