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.
- Org Manual, a good place to go.
- Org tutorials, curated org tutorial resources. Pick and choose what looks interesting to you, but I recommend beginning with the Rainer König video tutorials so you can see it in action quickly.
- Evil Mode: Or, How I Learned to Stop Worrying and Love Emacs, is a conversion resource for vim lover.
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.
- The data is mine. I own it. I store it. It’s easy to manage because it’s just a folder of text files.
- Any tool that works with plain-text, works with my notes. I can
catout a note from the command line. I can rungreporrgto search over file names or content. I can encrypt it if I want to withgpg. - Storage space for plain-text files is minuscule.
- Text is portable. If Emacs ceased to exist, I could still edit and read my notes just fine using any other text editor.
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:
- Python
- Management
- Budgeting
I keep notes for particular projects:
- 2021 Budget
- 2021Q3 Software Engineer Hiring
- Some Cleverly Named Internal Project
- JIRA-123 TITLE
I have notes for books I read, blogs I frequent, etc:
- Systemcrafters
- Linux Command Line and Shell Scripting Bible
- The Phoenix Project
And the departments in my Company:
- Sales
- Marketing
- HR
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.
:PROPERTIES:
:ID: aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb
:ROAM_ALIASES: Jane
:END:
#+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
:config
(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:
- How I take meeting notes leveraging Org-roam’s “dailies” features, to have even more information about who I talked to, when, and about what.
- The task management capabilities of Org and Org Agenda, and how I use them to store every idea that pops into my head, deferring them for later action without getting sidetracked.
- Reading my email from Emacs with a tool called “notmuch”, and how I seamlessly integrate action items that arise from email with my other tasks. I can reference emails from any note to provide more context for anything I’m thinking about. All without ever leaving Emacs.
- Sharing my notes in Google Docs, Markdown, PDF, HTML, or any other easily exportable target for the export features of Org.
- How I connect to PostgreSQL to run queries from Emacs in order to generate metrics reports on my Team and our software product.
- How I perform objective and data-centric performance reviews based on the information I can access about my team in Emacs and other tools.
- And all the other things I learn how to do in 2022.
I hope I’ll see you around.