Building an Org-mode Workflow: Timestamped Notes

by Jeff Bradberry

I love having logs for things that can be checked later on if need be, and so I enabled logging state changes and rescheduling into the LOGBOOK drawer way back in Scheduling and Deadlines. But since I have this nifty logbook, why not use it to capture yet more information? I wanted to be able to add my own custom timestamped notes. Fortunately, Org mode makes this easy.

My first known uses of this feature date back to 6 Mar 2023 for the state change notes, and 16 Mar 2023 for the arbitrary notes.

Usage

The obvious incremental step up from what I was already doing is to capture context when changing tasks from TODO to DONE. Perhaps this might be some info about why the change is happening, or perhaps some nuance that might need to be addressed in a separate task (this one particularly comes up in my pull request review tasks).

The way to record a note with the state change log item is to add the prefix C-u to the org-todo command (C-u C-c C-t). This opens up a buffer to prompt you to fill in a note, and the result looks like this:

** DONE review 118
CLOSED: [2023-03-06 Mon 10:56]
:LOGBOOK:
- State "DONE"       from "TODO"       [2023-03-06 Mon 10:56] \\
  noted that Tami is going in a different direction in PR 117.
:END:

That's terrific for when you want information attached to state changes, but what about when you want to log something without changing the state of the task? For that, you can use C-c C-z (org-add-note). My personal mnemonic for this keybinding is "C ommand journali Z e".

* [#3] annotate the new user info endpoint using DRF Spectacular
:LOGBOOK:
- Note taken on [2023-03-30 Thu 11:26] \\
  Doesn't seem to be needed?  I seem to recall that it shows up in
  Swagger UI, and no one has noticed anything missing from that section.
:END:

I believe that both of these commands can be used from the agenda views.

With these two commands, I can now keep a detailed chronology of the lifecycle of a task, without it getting in the way of the other information I need to see on a daily basis.

Settings

No settings were changed to accommodate these changes to my workflow.

The org-mode section in my .emacs file still looks like this:

(global-set-key (kbd "C-c l") #'org-store-link)
(global-set-key (kbd "C-c a") #'org-agenda)
(global-set-key (kbd "C-c c") #'org-capture)

(setq org-startup-folded 'showall
      org-agenda-files   (list "~/org/")
      org-refile-targets '((org-agenda-files :maxlevel . 5))
      org-refile-use-outline-path 'file
      org-log-into-drawer t
      org-log-done 'time
      org-log-redeadline 'time
      org-log-reschedule 'time
      org-priority-highest 1
      org-priority-lowest  5
      org-priority-default 4
)

Key Bindings Learned

  • C-u C-c C-t (org-todo with prefix): Change the state of the task but force the user to add a note which will be added to the LOGBOOK drawer along with the timestamped state change.
  • C-c C-z (org-add-note): Add a timestamped arbitrary note to the LOGBOOK drawer.

Next Steps

With all of the new things I was starting to track in Org mode, it was starting to get annoying to have to manually type it all in. Additionally, I was noticing some patterns that I could leverage. Next time, I'll talk about my use of capture templates to make things a bit easier on me.