| Home | Numbers | RAD | Org | diary

Org-Mode

Currently, I use org-mode on emacs on my laptop, and an Android app call "orgzly" to manage my org files away from /home. My org files reside in a Dropboxed directory called org-foo, and my main org file -- where most of my stuff goes -- is file called foo.org. I have a few other reference files, but the bulk of my TODO items and reminders are in the foo file.

start with a list

Suppose I have a few things I want to do, how would I use org-mode to get them done?

Well, I currently get paid to work on open-source software. I do some volunteer open-source work, mostly writing my own code to share with others. I also (sort of) have a life.

If I made a short list on any given day, it might look like this:

project: revamp the HTML docs
make sure API docs get generated and added to HTML docs
check links and images in HTML docs for this release
figure out how to do all the images just once to speed it up
keep expanding stormrider.io website
how do we communicate breaking API changes?
document MAAS CLI on personal website
text sharon
text adams
text nick
clear litterbox
take out trash
check temp/drip faucets
refresh cat's food
find glucometer (did i leave it at doug's?)
take a short nap
put fruit in crisper door to preserve it
put up last set of shelves to give me more space for t-shirts
vaccum the kitchen
read the bee-keeping book
have dinner with doug and sharon
standup meeting every wed at 9:30am (unless on holiday)

Like somebody once said, "this is an amorphous blob of un-doability!" How can i use org-mode to clean it up?

try outlining it?

Well, I can start by outlining it, maybe like this:

* project: revamp the HTML docs
  ** make sure API docs get generated and added to HTML docs
  ** check links and images in HTML docs for this release
  ** figure out how to do all the images just once to speed it up
* keep expanding stormrider.io website
  ** document MAAS CLI on personal website
* how do we communicate breaking API changes?
* people
  ** text sharon
  ** text adams
  ** text nick
  ** have dinner with doug and sharon
* housework
  ** clear litterbox
  ** take out trash
  ** check temp/drip faucets
  ** refresh cat's food
  ** put fruit in crisper door to preserve it
  ** vaccum the kitchen
* find glucometer (did i leave it at doug's?)
* take a short nap
* put up last set of shelves to give me more space for t-shirts
* read the bee-keeping book
* standup meeting every wed at 9:30am (unless on holiday)

Outlining is good for grouping things, but in my experience, it adds way too much bulk to the file. Besides, trying to keep my outline parallel is a lot of extra, unnecessary, and artificial work. About the only place where outlining is good is keeping things in projects.

maybe tagging is better

I prefer to tie everything together with tagging, which is a feature of org-mode. Re-working my list in terms of that idea, it would probably look more like this:

* revamp HTML docs                                :proj:osP:
  ** generate/add API docs                             :osP:
  ** check links/images for release                    :osP:
  ** run HTML images once for speed                    :osP:
* project: stormrider.io                               :osV:
  ** document MAAS CLI                                 :osV:
* communicate breaking API changes?                    :osP:
* text sharon                                      :friends:
* text adams                                       :friends:
* text nick                                        :friends:
* clear litterbox                                    :house:
* take out trash                                     :house:
* check temp/drip faucets                            :house:
* refresh cat's food                                 :house:
* find glucometer (doug's?)
* short nap
* fruit in crisper                                   :house:
* shelves for t-shirts                          :proj:house:
* vaccum kitchen                                     :house:
* bee-keeping book                              :proj:house:
* dinner with doug/sharon                          :friends:
* standup meeting (wed/9:30am)                         :osP:

This pattern is a lot easier to keep: I don't have to worry about finding the higher level of the outline, unless it's a project (which makes sense), and I just don't tag things if I don't know what they should be tagged. Not everything in life can be neatly categorized, and when you try to do that, you waste a lot of time and energy doing artificial things that have only a little marginal value.

using the TODO keyword

The org-mode tool has a special keyword to mark things that you want to do. Oddly, it's called TODO (though you can customise that if you want). If I mark all these things in that way, here's what I get:

* TODO revamp HTML docs                                :proj:osP:
  ** TODO generate/add API docs                             :osP:
  ** TODO check links/images for release                    :osP:
  ** TODO run HTML images once for speed                    :osP:
* TODO stormrider.io                                   :proj:osV:
  ** TODO document MAAS CLI                                 :osV:
* TODO communicate breaking API changes?                    :osP:
* TODO text sharon                                      :friends:
* TODO text adams                                       :friends:
* TODO text nick                                        :friends:
* TODO clear litterbox                                    :house:
* TODO take out trash                                     :house:
* TODO check temp/drip faucets                            :house:
* TODO refresh cat's food                                 :house:
* TODO find glucometer (doug's?)
* TODO short nap
* TODO fruit in crisper                                   :house:
* TODO shelves for t-shirts                          :proj:house:
* TODO vaccum kitchen                                     :house:
* TODO bee-keeping book                              :proj:house:
* TODO dinner with doug/sharon                          :friends:
* TODO standup meeting (wed/9:30am)                         :osP:

It doesn't seem like much, but there's an easy way to transition these items to a DONE status, and if you need to repeat them, there's a way to make them become TODO items at a later date.

specific appointments and repeat patterns

Some of these things are done at specific times, and some of these things I want to periodically repeat. This means assigning a date, which may include a time or a repeat pattern, or both. Here's now it's done:

* TODO revamp HTML docs                                :proj:osP:
  ** TODO generate/add API docs                             :osP:
  ** TODO check links/images for release                    :osP:
  ** TODO run HTML images once for speed                    :osP:
* TODO stormrider.io                                   :proj:osV:
  ** TODO document MAAS CLI                                 :osV:
* TODO communicate breaking API changes?                    :osP:
* TODO text sharan                                      :friends:
  SCHEDULED: <2021-11-17 Wed +1d>
* TODO text adam                                        :friends:
  SCHEDULED: <2021-11-17 Wed +3d>
* TODO text nicholas                                    :friends:
  SCHEDULED: <2021-11-18 Thu +3d>
* TODO clear litterbox                                    :house:
  SCHEDULED: <2021-11-17 Wed +1d>
* TODO take out trash                                     :house:
  SCHEDULED: <2021-11-17 Wed +1d>
* TODO check temp/drip faucets                            :house:
* TODO refresh cat's food                                 :house:
  SCHEDULED: <2021-11-17 +1d>
* TODO find glucometer (doug's?)
* TODO short nap
* TODO fruit in crisper                                   :house:
* TODO shelves for t-shirts                          :proj:house:
* TODO vaccum kitchen                                     :house:
  SCHEDULED: <2021-11-21 Sat 10:00 +1w>
* TODO bee-keeping book                              :proj:house:
  SCHEDULED: <2021-11-17 Wed 21:30 +1d>
* TODO dinner with doug/sharon                          :friends:
  SCHEDULED: <2021-11-17 Wed 18:30 +1d>
* TODO standup meeting (wed/9:30am)                         :osP:
  SCHEDULED: <2021-12-01 Wed 09:30 +1w>

This works pretty well, but the other items don't show up in my org agenda, because they don't have dates on them. Org-mode intends to take care of this with two different lists: an agenda, which has things tied to a specific time or day, and a to-do list, which just has things that are TODO items, regardless of scheduling. This is backwards for me; I can run the TODO list and see things that are scheduled, but not organise them by schedule; I can run the agenda, but not see things that aren't scheduled.

a workable agenda

To get things visible my way, I assign dates to everything in my list, and then just move them forward every day until they're done. Sometimes, I even leave them as undone on the day they were created, until I can get to them (this bubbles them up to the top of the agenda). My new list would look like this:

* TODO revamp HTML docs                                :proj:osP:
  SCHEDULED: <2021-11-17 Wed +1d>
  ** TODO generate/add API docs                             :osP:
  SCHEDULED: <2021-11-17 Wed>
  ** TODO check links/images for release                    :osP:
  SCHEDULED: <2021-11-17 Wed>
  ** TODO run HTML images once for speed                    :osP:
  SCHEDULED: <2021-11-17 Wed>
* TODO stormrider.io                                   :proj:osV:
  SCHEDULED: <2021-11-17 Wed +1d>
  ** TODO document MAAS CLI                                 :osV:
  SCHEDULED: <2021-11-17 Wed>
* TODO communicate breaking API changes?                    :osP:
  SCHEDULED: <2022-01-10 Mon>
* TODO text sharan                                      :friends:
  SCHEDULED: <2021-11-17 Wed +1d>
* TODO text adam                                        :friends:
  SCHEDULED: <2021-11-17 Wed +3d>
* TODO text nicholas                                    :friends:
  SCHEDULED: <2021-11-18 Thu +3d>
* TODO clear litterbox                                    :house:
  SCHEDULED: <2021-11-17 Wed +1d>
* TODO take out trash                                     :house:
  SCHEDULED: <2021-11-17 Wed +1d>
* TODO check temp/drip faucets                            :house:
* TODO refresh cat's food                                 :house:
  SCHEDULED: <2021-11-17 Wed +1d>
* TODO find glucometer (doug's?)
  SCHEDULED: <2021-11-17 Wed>
* TODO short nap
  SCHEDULED: <2021-11-17 Wed>
* TODO fruit in crisper                                   :house:
  SCHEDULED: <2021-11-17 Wed>
* TODO shelves for t-shirts                          :proj:house:
  SCHEDULED: <2021-11-17 Wed>
* TODO vaccum kitchen                                     :house:
  SCHEDULED: <2021-11-21 Sat 10:00 +1w>
* TODO bee-keeping book                              :proj:house:
  SCHEDULED: <2021-11-17 Wed 21:30 +1d>
* TODO dinner with doug/sharon                          :friends:
  SCHEDULED: <2021-11-17 Wed 18:30 +1d>
* TODO standup meeting (wed/9:30am)                         :osP:
  SCHEDULED: <2021-12-01 Wed 09:30 +1w>

Note that I moved one of them out a ways (the "breaking API" doc), since it doesn't need to be discussed for a couple of months. Also notice that, while I made individual project steps non-repeatable, the projects underneath them repeat every day. This forces me to deal with the individual items, but allows me to easily keep the projects going until they're done.

using the diary tool

If you look closely, you'll see there's now only one TODO item that isn't scheduled, the "check temp/drip faucets" task. Because the cold season is only from November to March here, there's no need for this one to show up on any day from April to the end of October. Org-mode doesn't explicitly handle these types of repeats. Instead, it permits integration with an older scheduling tool called the diary.

I won't get into all that, but the entires can be added to your org-file items by enclosing them in pointy-braces, as shown with the "check temp/drip faucets" entry below:

* TODO revamp HTML docs                                :proj:osP:
  SCHEDULED: <2021-11-17 Wed +1d>
  ** TODO generate/add API docs                             :osP:
  SCHEDULED: <2021-11-17 Wed>
  ** TODO check links/images for release                    :osP:
  SCHEDULED: <2021-11-17 Wed>
  ** TODO run HTML images once for speed                    :osP:
  SCHEDULED: <2021-11-17 Wed>
* TODO stormrider.io                                   :proj:osV:
  SCHEDULED: <2021-11-17 Wed +1d>
  ** TODO document MAAS CLI                                 :osV:
  SCHEDULED: <2021-11-17 Wed>
* TODO communicate breaking API changes?                    :osP:
  SCHEDULED: <2022-01-10 Mon>
* TODO text sharan                                      :friends:
  SCHEDULED: <2021-11-17 Wed +1d>
* TODO text adam                                        :friends:
  SCHEDULED: <2021-11-17 Wed +3d>
* TODO text nicholas                                    :friends:
  SCHEDULED: <2021-11-18 Thu +3d>
* TODO clear litterbox                                    :house:
  SCHEDULED: <2021-11-17 Wed +1d>
* TODO take out trash                                     :house:
  SCHEDULED: <2021-11-17 Wed +1d>
* TODO check temp/drip faucets                            :house:
  <%%(diary-block 11 01 2021 05 01 2021)>
* TODO refresh cat's food                                 :house:
  SCHEDULED: <2021-11-17 Wed +1d>
* TODO find glucometer (doug's?)
  SCHEDULED: <2021-11-17 Wed>
* TODO short nap
  SCHEDULED: <2021-11-17 Wed>
* TODO fruit in crisper                                   :house:
  SCHEDULED: <2021-11-17 Wed>
* TODO shelves for t-shirts                          :proj:house:
  SCHEDULED: <2021-11-17 Wed>
* TODO vaccum kitchen                                     :house:
  SCHEDULED: <2021-11-21 Sat 10:00 +1w>
* TODO bee-keeping book                              :proj:house:
  SCHEDULED: <2021-11-17 Wed 21:30 +1d>
* TODO dinner with doug/sharon                          :friends:
  SCHEDULED: <2021-11-17 Wed 18:30 +1d>
* TODO standup meeting (wed/9:30am)                         :osP:
  SCHEDULED: <2021-12-01 Wed 09:30 +1w>

There's more to come, but this is a really good start.


Updated 2021-11-19 Fri 09:30 by Bill Wear (stormrider)


Copyright (C) 2020 by Bill Wear. All rights reserved, but asking to use is permitted and welcome.