My BASB Implementation in Org Mode v2023-06
This post is part of the Building My BASB in Emacs - 2023 Capstone Report series.
Table of Contents
|[Personal Knowledge Management]
The meat and potatoes of the series! The stuff you’ve probably been waiting for!
Rather than dump the entirety of my init folder on you, I’ve opted to give a more narrative explanation of how the system came to be. If you are unclear about anything, please reach out on the socials and I’ll do my best to clarify.
Reminder: I use the term BASB to refer to the solution we’re building in Org.
I’m sure I’ll update this page more than a few times, but expect I’ll write a new version after enough time passes.
There aren’t that many global configurations I want to call out at the top. Generally, I write my init file in org, add packages and comments that I want to try, and add in commands I want to keep handy to my general.el keymap.
That said, there is one thing I want to encourage anyone considering org to take a look at: you should reverse the insert order of headings so that new entries come in at the top… a “reverse cron” approach to insertion if you will… rather than the default of appending to the bottom.
I’ve found that this approach leverages the fact that we tend to want more recent things more at hand than older things. Plus if you stick wth the system for a while, appending to the bottom often entails a lot of scrolling.
Your mileage may vary, but worth noting.
BASB: Beginning with the End in Mind
I find that the nature of BASB creation inclines people to focus on the BASB as the target output. But that’s of course, not the real goal. The real goal is to figure out what other stuff this new tool/practice enables. Keeping that in mind, I find I can’t talk about the thing without talking about what I use it for and want from it first.
As such, I will walk my setup through each of the target use cases I aim to solve. I’m sure it will evolve as I add more, but the needs here are what drive the system, not the system driving my needs.
My Target Use Cases
Journaling and Regular Reviews
This is the number one use case because creating a regular habit that uses the tool multiple times per day is key to really learning it. Journaling isn’t a technically complicated use case, just requiring some templates and a place to journal in the system that doesn’t require thinking about where the entry goes.
I took a cursory glance through various options inside of org, and opted for using org-roam’s dailies to handle this. I’ve used diary mode in the past, but I liked org-roam’s capture system that was tied to it, so I went that direction. I also use org-roam for other things which I’ll describe later, so that was a reasonable fit.
This does mean that I break my principal of a single org file almost immediately, since org-roam does separate daily files by default. However, experience has taught me that I never mess with these physical files themselves, so I think it’s fine. Putting journals in one file is also a surefire way of eventually causing a performance problem somewhere down the line. Might as well head that one off before we get there.
Additionally, I keep all my templates as org files in a sub-directory,
~/org-roam-repo/templates. I find using full org files much easier to visualize and edit rather than storing them as strings in my init file. I mean, I can only handle so many
\n’s before my eyes cross… and I’m a person who likes regular expressions.
This also shows the first example of my principle for subdirectory use in org:
Prefer a flat, single directory where possible. Use sub-directories for programmatic separation of content as needed.
In this case, having a single template directory (no files of which are included in the org-roam index) makes them easier to find, refer to, and keep out of the way of other files in BASB.
The following templates apply to this use case:
- Morning Journal
- Evening Journal
- Weekly Journal
- Monthly Journal
- Interstitial Journal
Daily notes themselves go in a special subdirectory,
~/org-roam-repo/journals. The same reason as above applies, in that org-roam expects a directory to work with for journals, and I find separating them out is easier for various completion frameworks to handle rather than co-mingling them with other files. After all, today’s journal is very relevant. Tomorrow’s much less so. Even less before that. And on and on… No need to have all the clutter if I don’t need it.
And with just that, we’ve got a perfectly serviceable digital journal that I can copy, paste, and link into/out of which I interact with each morning and night. Not bad for minimal effort (though I’ve implemented enough PKM’s to know this is an easy case).
A huge but not-so-obvious reason we tackle this use case first, is that daily journals create space for process that helps fill any gaps in the rest of our setup. With a simple checklist as part of my evening journal, I can remind myself to do all kinds of things at the end of the day.
Maybe I need to do something manually for a half-baked process I didn’t finish. Maybe I need to reflect on if a piece of tagging overhead I added is still worth it. Maybe I need to scan Snipd for any useful clips rather than try to figure out a Rube Goldberg integration with it. Whatever the needs are, starting with journaling gives a regular means of repairing or revisiting any issues that might arise as we build out BASB.
Saving Notes, Links, and Other Ideas
For pretty much anything, from spur of the moment thoughts to taking my own notes on a meeting, I’ll fire up my Interstitial Journaling capture template and throw it in the Daily Note. The idea is to minimize the energy wasted around “where does this go?” Answer: The Daily Note. Done. I can refile it later, and if I don’t I can full-text search the directory.
In fact, I do refile them later… during my evening journal. There’s a checklist item to review the non-journal entries and refile them to PARA. There aren’t usually very many, and org-refile makes it extremely easy to do.
From time to time, I’ll take notes directly in a relevant PARA section. But often it Daily Note first, then refile.
Now we get back to the principle I mentioned earlier: putting everything in one org file. PARA is a great framework, so I have a file simple named PARA.org with Projects, Areas, Resources, and Archive as the top level headings. There are sub-bullets of all the things you might expect under those headings.
To be clear, this is not the org-roam way, but it is the org way. This way we get to earn any complexity we add to the system. I keep all my notes for various things in that single file, and if it feels too unwieldy, then I’ll bud it off into it’s own org file.
Having been through this before, I stubbed my favorite 9 or so Areas and Resources to start, and will let the rest grow over time. I give each heading I want to refile to an ID via a custom function I wrote (timestamp_heading) so I can use
org-roam-refileto refile any other notes there. I also add a
Thoughtssub-bullet under each and do the same, for any miscellaneous info I want to refile to the right Area without thinking about what subsection it should belong to.
It might have been possible to use a many-file approach instead. With clever tagging or filing or something, I could have probably used
org-qlto compile this PARA view from the bottom up. I opted not to do this because:
- I couldn’t find an easy way to do it with a little Googling. Experience in emacs land tells me if a few Google searches don’t find what you’re after, then it will be much harder (though not impossible) to implement. Most people pick a relatively small number of org files if they aren’t going all in on org-roam or deft, so I think that’s fine to start. Even if I ultimately grow to have an org file per sub-Area, that list probably won’t be more than 20 or 30 files… maybe 100 in the long term.
- Tagging consistency is really hard, and really underestimated. Auto-complete is a huge help, but if I can just file something once, I’d rather do that than remember how to tag stuff over and over, especially in a distributed system. Inheritance with hierarchies is clear and easy to work with.
- Tagging is a great theoretical concept for Information Management, but that’s not what I want to spend time focusing on. If I can get to a 95% good enough solution with 5% of the effort, then I’ll do that. Or in another sense: if I can remove a small mental tax that I would pay every time I made a new note from now into the future, no matter how small, I think that’s probably a good call.
Now, things do get a little sticky in a few places when we get to parts of this use case outside of text files on a single Linux desktop.
Ah mobile… a top request of many and a bane of many a PKM tool’s existence. I’ve personally used Obsidian and Logseq’s native Sync, as well as Roam when it was web based.
In pretty much every case the experience is awful. Conflicts happen that you don’t expect, resolution flows are awkward, plugins kept getting weird for me (especially in Obsidian), and on and on…
Emacs is not immune to these issues, but stepping on a few thorns in the past helps clarify exactly my priorities.
First, I want to be able to capture ideas quickly on mobile, either mine or from another app. The fewer clicks the better, and if it works with the
Share with...menu on Android even better.
Second, I want to be able to view all my notes when I need them on the go.
Notably, I don’t find editing the bigger system to be very important, because typing on mobile is terrible anyway. I would like to be able to see info about a contact before I jump into a meeting with them when I’m out and about, but I can capture any new info as a new note and refile it later.
I solve these cases with a three-pronged approach on my Android phone.
First, I need to get the files on my phone at all. Here, SyncThing is the answer. It’s like Dropbox but one you run yourself with no server required. It’s easy enough to install on multiple machines (from Android to Linux to Windows to Mac), and does its job. I sync all of my org notes to the phone, though I have a sub-directory
mobilefor a few specific files I’ll cover in a second.
Second, Orgzly solves the capture use case wonderfully (along with TODOs, see below). It’s easy to capture notes via the widget, and the app is easy enough to understand. To minimize its impact on the broader PKM system, I only point it to the
mobilesub-directory which contains three files: TODOs.org, Keep.org, and Contacts.org. Since I do edit these files on my PC, I have to be mindful about giving some sync time before jumping back onto my phone. My typical flow is to jot down things on mobile, then refile them at night. Very little goes the other way (except for TODOs). Keeping Orgzly’s impact to a few files also keeps it from overwriting files where I care about whitespace formatting, which I hear is a problem for others that have tried to be all in on Orgzly.
I want to add, my first iteration of capture was to just
Share with...to Google Keep and then copy those into BASB each night during the evening journal as a checklist item. The copying and pasting back and forth got annoying, and I find capturing straight to an org file from Orgzly lets me use one refile command at night to get it where it needs to go. So I switched… but that’s where the Keep.org namesake comes from.
Third, for viewing all of my notes, I use Orgro, which is a much cleaner viewing experience than Orgzly since that’s all it does. This I can point to the whole org directory, find what I know is there, and get out again.
This setup works most of the time, and it’s fairly straightforward for me to resolve conflicts when the arise via ediff (which is worth learning if you haven’t used it before). But, mobile is a pain point for everyone, and I personally believe the “need” for it is significantly overblown.
Pictures and Other Attachments
While most of what I capture and deal with is text, I do keep a running doc of how I want to improve my dress style, with visual inspiration I pull from around the web. So I do need to meaningfully handle pictures. There are two options I see mentioned a lot around the web.
The first is org-attach. There are a lot of cool things about org-attach. It isolates files in note specific directories. It has a link inference mechanism so your URI’s don’t get too long. It encourages using the
idproperty, which we’re already using for org-roam.
A big use case for BASB is the ability to pull together old work and remix it into something new. The actual link in the text, if copied, will change context when pulled into a project with a different ID. There are workarounds, but for my simple case, I think I’ll just link to the files in a directory outside the org folder on disk.
I specifically have a different folder outside the org directory because I don’t want to sync a bunch of binary blobs to my phone. I suspect that folder could get large much faster than the org directory itself with modest use.
org-downloadis a good enough helper for the time being, with a prefix to the folder outside my main org folder. That directory is relative to $HOME, just like my main org folder, so as long as I can set $HOME (even on Windows), everything will find it just fine, and moving links around in org won’t matter.
To walk the path of emacs is to always be looking for things to be better. I have my eye on a few things for the future that I haven’t bothered to implement yet.
- Move the Archive to a separate file, for all the things that fall out of scope and shouldn’t show up as refile targets. I don’t imagine this would be necessary unless there are either a huge number of name conflicts, or if size really gets out of hand.
- I’m thinking about pulling Contacts out of the mobile folder and putting it in the root directory, as I put it in there before I found Orgro. I like that I can add to it in a pinch via Orgzly, but I’m very used to adding a new quick capture and refiling it later these day. I chalk this under “not bothering” for now.
- Try out Voit’s method of being completely filesystem agnostic: https://karl-voit.at/2022/02/10/lfile/. My concern here is that I regularly shift between all major OS’s, and this might not be so easy to achieve on Windows.
There are approximately a hundred different ways to model a project in Org mode. I’ve already iterated through a few approaches, but rather than catalog each one, I’ll just detail where I’ve landed for now.:
- A project is a headline with the tag
project(set to not inherit in my init)
- The project itself has a deadline on the root node, which is the title of the project
- There are a lot of sub-headers I defined in a capture template to help the project stay contained and on track. I don’t use them every time, but it’s good to see a list on new project creation. Use can insert capture templates at point by preceding them with
C-0, even if you’re using general.el
- Notes can be refiled in from elsewhere with org-roam-refile once I add an ID
- For fleeting thoughts that are project specific, I’ll refile them into the project
- For things already in other places in BASB, I lean toward copying into the project, rather than a full refile
- Artifacts that live elsewhere like Google Docs and such are linked
- For me, this happens very often, as no one else I work with uses emacs, org, and so on
- I tend to brainstorm in Org and then export out to other systems for collaboration
- When finished, the project is refiled to a
Completed Projectssection in the Area
- I couldn’t figure out a good way to retain the category when Archiving them otherwise
- But also, reporting is a terrible use case to optimize for in general. I strive to optimize for doing, not for reviewing
This approach distributes all the projects in their various areas, but allows me to see any I’ve committed to through the agenda.
The challenge I ran into next was what to do about the (rather large) pile of someday/maybe project ideas. Stored in their own Area and Resource sections, they seem too disparate and hard to visualize together. Stored in the projects section they could be prioritized, but would quickly get blurred into mush.
Surely there was a way to keep the entries nestled in their Areas and to still see them fairly grouped together? Do I turn to alphapapa, his name be praised?
In short, yes. Enter
org-ql. While it seemed like overkill to figure out a view to pull all the projects together, this is a great tool to auto-group by category (which I’ve added to each Area) and see all the relevant info.
TODOs for each project are kept somewhere under the project header. One section I use a lot that borrows from the BASB course is the
Intermedite Packets section. Its headlines are like discrete sub-projects but with a more targeted focus to a discrete, deliverable unit of work. It helps a lot to crystalize a bigger project into smaller chunks. That said, I’ve noticed I have to be careful not to be too beholden to the list. Otherwise the uninformed me of the past might boss around current me into IP’s I discover aren’t the right things to do first once I get going.
- Use org-transclude instead of copying in notes
- I hear good things, and I doubt I would need the text directly in any exports, so it seems plausible
- Use org-transclude instead of copying in notes
Hand in hand with projects, of course, is TODOs. Org supports these natively, so there isn’t too much to cover given the above, but I’ll call out the interesting pieces.
The big trick is that TODOs.org is one of the three files I have Orgzly paying attention to on my phone. This lets me use the widget to see upcoming TODOs, capture them on the go, and get alerts on my phone base don the timestamps. I do add to and update TODOs from my desktop as well, so I need to be a little careful when syncing, but Nick Anderson points to a way to use Tasker to kick off an Orgzly sync on screen wake, and that’s pretty much kept everything running smoothly. Even if issues do pop up, it’s very easy in Orgzly to reset by force pushing or force pulling, depending on which is best.
I do occasionally forget to save a file (particularly from the agenda), so I’ve added in auto-save for buffers that aren’t saved after 60 seconds.
Most of my TODOs live in that file. However, I also keep TODOs in my projects as well. The PARA file is already in the org-agenda, so the only drawback is that those don’t sync to mobile. Currently, I’m ok with that, because if I’m being honest with myself, I don’t do that kind of work on my phone when I’m out and about. A key insight of David Allen’s Getting Things Done is that we do some things best at particular times and contexts. I find a lot of people in the PKM space try to stuff everything into mobile when they really won’t get much productive output from it. It’s a classic 80/20 issue. If there is a task I do want to stew on while I’m about, I can either find it in Orgro, or copy it into my TODOs.org file as a one-off, though that case so far has yet to actually happen.
Time for contacts!
Now, unlike most people who get elbow deep in emacs land, I’m not interested in bringing everything under the sun into org mode. It could theoretically be useful to have all my contact data in one place, but Org mode doesn’t plug well into non-emacs systems. My email client is GMail. Google Contacts syncs to my phone without issue, and it’s nice to see names when people text me. I don’t really need to tinker with caldav and vcard import/export because those parts are working fine right now.
What I do need from a CRM (contact relationship management system), is the following:
- A way to tell who I should reach out to and check in on (I am awful at this)
- A way to pull together notes on a specific person into one place from multiple meetings
- A way to view contact notes before talking to someone, with or without my laptop
There is a contact management thing for org called
org-contacts, but more than being under-documented, it doesn’t seem to help with my core user journeys above. I don’t really care (for now) about storing contact info in different ways. I don’t need it to play nice with mu4e or other emacs email clients. However, the idea of all the contacts in a single file does make sense to me in the vain of being as simple as possible.
So, my current flow looks like this:
- Create a new entry in the contacts file from a template
- Refile them to a Tier in the Contacts.org file (some people should be contacted every 3 weeks, some every year, some in between)
- Reschedule the recurring TODO to follow up based on the Tier they’re in
- Watch the org agenda for when to follow up
- Take notes on meetings and communications as Interstitial Journal entries when they happen
- Refile those entries to the subheading
Timelinein the contact and update the follow up TODO
A lot of those edges are a bit manual and could go wrong, but for the contacts I care most about right now it’s working well enough.
- Have the recurring timestamps be derived from the Tier the contacts are in, rather than setting them up manually
- I go back and forth on this, as it’s also useful to set the follow up to a shorter period of time if needed. So I’ll leave it as is for now.
- Have the last touch timestamp update when I refile a note to its Timeline
- The last touched timestamp is a holdover from Obsidian
- I haven’t written a report to see when I last talked to all my contacts, but when I do I’ll judge if this approach is better or if I can find the most recent inactive timestamp under a contact easily enough
- Have a way to surface contacts I’m meeting with next in a buffer of some kind
- This involves bringing more scheduling info into Org, which I’m not inclined to do since Google Calendar is good enough for now
- Have the recurring timestamps be derived from the Tier the contacts are in, rather than setting them up manually
One of the things I’m working on in my life right now is cooking. I’m trying to get good at it both for fun and for feeding my family. The big key seems to be iteration, and iteration is best done with notes!
I broke out recipes into its own file from the start, because I sensed it would be big and unwieldy from the start. The Top level headings are:
- Ideas to Try
- Prep Staples
- Main Dishes
- Side Dishes
Each Recipe is a heading in one of those groups with notes on the background and research, my own shorthand for the recipe, and a section for Experiments which are all preceded by a timestamp. Experiments all have sections for Notable changes, Results, and Things to Try Next Time.
Style Inspiration and Thoughts
This is possibly the most undefined use case thus far.
While I think the use case by use case breakdown is a better framing and more informative than purely looking at the CODE framework, I thought I would run through it here should there be any interest from the BASB community.
Breaking down capture by type of information source:
- Read on Kindle if possible and capture via Readwise
- Read through Readwise Reader and capture there
- Usually capture a link on mobile via
Share with...to Orgzly
- Refile and take notes as needed after Evening Journal
- Usually capture a link on mobile via
- YouTube Videos
- I’ll generally take notes directly in emacs in an Interstitial Journal entry
- Then I’ll refile it where it should go
- Snipd is my podcast player, which allows for clipping
- I DO NOT use the Readwise export, because I find it too noisy
- Instead when I’m done with an episode, I’ll share the notes via Orgzly and think through those notes later in BASB
- Meeting Notes
- Capture in an Interstitial Journal
- If part of a work meeting, refile to the right section there
- If part of a 1:1 personal contact meeting, refile to their Timeline section
- My Own Thoughts
- Interstitial Journal or Orgzly entry, depending on if I’m out or at my desktop
- Refile as needed
This is mostly covered elsewhere, but I try to stick to one PARA file if possible, and bud off pieces that should be separated for programmatic reasons, or if I know they’ll be really hairy sections (work, Recipes, etc.).
I do want to add that org-roam is amazing for being ID based, which allows for incremental change when using it. Other similar tools require going a bit more all in on their preferred file structure. I like that org-roam doesn’t.
I tend to blend some beliefs from Zettelkasten into this step, rather than adopt Tiago Forte’s approach wholesale.
I don’t think highlighting is especially valuable as a practice, even when I was using Evernote. Even in an iterative fashion, I just found it didn’t resonate with me.
That said, I do think that rephrasing in your own words is super valuable. The whole idea of fleeting notes > literature notes > permanent notes is leveraging the power of your own interpretation to make the information more yours. I don’t see a reason to put that step off like Tiago does.
I’ll often use a
<< to denote personal thoughts as opposed to a good-faith transcription of ideas when I’m taking notes. I might want to tinker with a personal summary at the top at some point… but in either case I wholly embrace getting to the part where I rephrase things, rather than waiting for multiple passes at the material.
This is a tough area for me, but I’m working on a few avenues for it.
First, there’s this blog! It took a while to get around to setting up ox-hugo, but now that I have I’m very happy with the outcome. I’m hoping more personal blog posts will be on the way.
Second, part of my Stoic practice is to read r/Stoicism and respond to someone who’s asking a question every morning. I actually use the reddit app to scan the posts, but then I’ll use redigg to pull in the actual text and write a response in org mode. Then I’ll convert via blackfriday and paste it back to reddit. I’m hoping to add these posts to my own blog at some point, since I don’t like how siloed they are in reddit. The recent API fiasco might break this flow soon.
Third, I’m working on a few work projects that involve research and expression. I won’t go into them much here, except to say I’m using all the techniques I’ve mentioned so far to try and build a better public understanding of Dynamic Observability.
Building My BASB in Emacs - 2023 Capstone Report series
- My Path to Org Mode
- Should You Choose Org Mode?
- What Makes Org Mode Hard for PKM
- My BASB Implementation in Org Mode v2023-06
- Things Left Unimplemented… and I'm Unsure if I Ever Will