William Vaughn

VP of Emacs: A Personal Wiki In Plain Text

VP of Emacs is a blog series about using Emacs as an essential tool in my job as the VP of Software Engineering at Carbon Lighthouse. I’m a software engineer trying to cut it in a job that has required me to be more organized, communicative, strategic, and personal than ever. Emacs helps me get more done and keep it all connected. It has become the application I use everyday to unify note taking, emails, task management, writing, programming, and more.

Watch the YouTube video that accompanys this blog.

A personal wiki with Org and Org-roam

A realization I had when I started doing software management was that I could no longer safely forget something and expect someone else to keep track of it. As a manager, I am the one expected to keep track of things. I don’t naturally multitask well, and when something is out of my sight it is well and truly out of my mind. If I were to have a chance at being a supportive and effective manager I knew I would need to find a way to augment my brain with something slightly addictive to use. When I first fired up an Org buffer I knew I had found a tool that appealed to my hacker nature in a way that would keep me coming back. Sometimes Emacs demands my attention and focus, I get sidetracked by a configuration tweak or technical fidgeting, but most of the time Emacs is a net-positive influence on my productivity.

Org is a plain-text file format for taking structured notes, as well as an Emacs mode that adds astonishing functionality for editing and interacting with .org files. Org is one of the “killer apps” for Emacs, it’s widely used and well supported. Most of my work revolves around Org in some way or another. If you haven’t ever used org-mode, I’d encourage you to get a feel for it.

Built on Org’s powerful base, lies Org-roam, a knowledge management system based on the features and approach of a proprietary research tool called Roam Research. Org-roam transforms a folder of disconnected .org files into a connected wiki and database of personal knowledge. Some people call this approach “building a second brain”, others refer to it as the Zettelkasten method. Whatever you call it, the result is being able to see connections between all of your notes that you couldn’t see before. Every page in roam has a list of “backlinks” to everywhere that page was mentioned. I’ll drive home the value of this as a software engineering manager with a simple but illustrative example.

At any time, I can go to the Org-roam page for my CEO to see the details of any conversation or meeting I have had with him, ever.

That doesn’t only apply to my CEO, that applies to everyone I work with. If we’ve had more than one conversation and done anything I might consider important business, you have an Org-roam page in my system.

Tools like Evernote, Todoist, Superhuman, and Roam Research are enough to do anything I’ll write about in this blog series, but there are benefits I like about this plain-text approach to note taking that you don’t get with any other app.

Everyone and every thing gets their own org-roam note

Everyone I work with has an Org-roam note that becomes the central hub of information I have about them. People are the most significant part of my system, but they aren’t the only thing I keep track of.

I have notes by topic:

I keep notes for particular projects:

I have notes for books I read, blogs I frequent, etc:

And the departments in my Company:

The more completely I link related ideas, the better the graph of my knowledge becomes. I want to be able to see how all of these people, ideas, and resources relate to each other. The purpose of taking notes this way is to be able to recall and rediscover information when it is needed. The more linked, the easier my knowledge is to traverse. I try to set aside time a few minutes a day to quickly scan, groom, and link notes. I go deeper during my weekly review sessions, often moving notes around or inserting links between them.

Here is what one of my buffers might look like for one of my direct reports.

:ID:       aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb
#+title: Jane Doe

Lead Software Engineer at Carbon Lighthouse

* Contact
- Phone: 555-1234
- Email: jane.doe@carbonlighthouse.com

* Personal
- Her son is John Jr 3yo
- She is an accomplished rock n' roll musician, drummer

* Performance Reviews
** 2021H2 Data Gathering...
** 2021H2 Performance Review...

* 2021
** 2021-09 September
*** 2021-09-15 Wednesday...
*** 2021-09-15 Wednesday...
*** 2021-09-29 Wednesday...
** 2021-10 October
*** 2021-10-06 Wednesday...

It contains contact information, some reminders of personal details, performance review notes, and a datetree of our one on one meetings. The one on one meetings are shown using a collapse feature of Org in order to hide their details. In addition to this information, the Org-roam buffer shows the list of backlinks to everywhere Jane has been linked. These two buffers alone give me a great jumping off point to contextualize how well Jane is doing in her role. I often have a record of feedback she’s given and received, links to project’s she’s working on, notes on her contributions to team meetings, and more.

One on one meetings

The one-on-one or “o3” is the most important meeting I have as a VP of Engineering. I schedule 30 minute meetings once a week with my direct reports and I have many bi-weekly, monthly or quarterly touch points with other people in my department and around the company. Even though these meetings are somewhat informal and loosely structured I still treat them seriously. I rarely cancel them, and if I do then I’m sure to reschedule promptly. Because these meetings are so meaningful I like to be reasonably prepared for them, but I don’t usually take more than 5-10 minutes to prep. When I know I have an o3 coming up with a person I will navigate to their Org-roam file and run a specialized o3 org-capture template to make a new entry in their datetree.

Here is the simple template org/capture_templates/o3.org with an agenda for me to fill in with my items before the meeting and to record anything that comes up during the meeting.

* Direct (10m)
* Manager (10m)
  - %?
* Future (10m)
* ARs [/]

If today is Wednesday, Jan. 05 and I navigate to Jane’s file in preparation for an o3, I can type SPC X o to automatically insert the template into that Jane’s datetree for today’s date.

* 2021
** 2021-09 September
*** 2021-09-15 Wednesday...
*** 2021-09-15 Wednesday...
*** 2021-09-29 Wednesday...
** 2021-10 October
*** 2021-10-06 Wednesday...
* 2022
** 2022-01 January
*** 2022-01-05 Wednesday
**** Direct (10m)
**** Manager (10m)
  - Type something here
**** Future (10m)
**** ARs [/]

The above can also be done on Monday, Jan. 03 in preparation for a meeting that happens Wednesday by typing SPC u 1 SPC X o. This version of the command prompts the user for a date before inserting the template into the file.

This is a capture customization of Emacs and Org that helps me do something specific to my particular workflow. All it takes is a little Emacs Lisp.

(use-package! org
  (setq org-capture-templates
        '(("o" "o3" entry
           (file+olp+datetree buffer-name)
           (file "capture_templates/o3.org")))))

This change sets some options that inform Org how to do all the heavy lifting. Maybe this is something you could imagine seeing in the preferences menu of your favorite note taking application. However, this is quite different than that because of what it reveals, that Emacs is configured by the elisp programming language. Emacs can be thought of as an elisp interpreter or framework for building applications, especially applications that involve text processing. In the long-term this is the most important feature of Emacs, it unlocks the power for every individual to make Emacs into whatever they want it to be. If that’s intriguing to you, I hope you’ll keep reading as I lay out more of the ways I am weaving my software organization management philosophy into Emacs.

Coming up next

Some of the things I have in mind to write more about are:

I hope I’ll see you around.