A compelling feature of Org is its ability to interpret a headline as a task. Org provides a rich set of attributes to a headline, many of which affect how it is rendered in Org Agenda. While it is easy to annotate a headline with attributes to get an approximation of desired intent in Org Agenda, using said attributes with an incomplete understanding of them can lead to surprising behavior. I found this especially so when using scheduled timestamps.

This post offers guidance on how different types of tasks can be implemented with an Org headline with the intent of minimizing surprise when rendering them in an Org Agenda (henceforth referred to as agenda) view.

Task Attributes

If we define a task as a piece of work to be done or undertaken, there are a number of attributes we can apply to it to describe different types of tasks. Such attributes can make a task:

• appear in the agenda at a specified time
• have status (aka state, progress) that can be tracked
• begin at a specified time
• have a deadline at a specified time
• repeat over time
• have a nested number of sub-tasks
• have a priority associated with it

In Org, any headline can be considered to be a task. In what follows, we will detail how the attributes described above can be implemented in Org. Note that, particularly with timestamps, multiple implementations achieving the same end can exist; this post will not enumerate through all of them for the sake of brevity.

The task is to appear in the agenda at a certain time.

Adding a plain timestamp to the body beneath a header will display it in the agenda view. Such a task is referred to by the Org manual as an event or appointment.

* Dentist Appointment
<2023-08-22 Tue 15:00>

Multiple timestamps are supported for the same event. With the example below, the headline Dentist Appointment will show in the agenda view for both Tuesday and Monday.

* Dentist Appointment
<2023-08-22 Tue 15:00>
<2023-08-28 Mon 13:00>

Note that the task does not have to have status (for example TODO, DONE) associated with it to be displayed in the agenda view.

The task’s status (aka state, progress) is to be tracked.

A headline can be turned into a task with status using the TODO attribute. If there is no timestamp associated with the headline, the task can still show up in an agenda if an Org Agenda command that lists out all TODOs is called. An example TODO item is shown below.

* TODO Fix Form Bug

The task begins at a specified time.

A timestamp prefaced with the key word SCHEDULED informs agenda that work is to start on that specific time. If the task is a TODO item, the task will be displayed in the agenda timeline only if its state is not DONE. The significance of this is that an agenda view will not display a DONE item that is scheduled by default. If the desire is to see the headline in the default agenda timeline regardless of task status, use a plain timestamp as described above.

* TODO Get Groceries
SCHEDULED: <2023-08-26 Sat 14:00>

A headline can have both a SCHEDULED timestamp and one or more plain timestamps.

* TODO Get Groceries
SCHEDULED: <2023-08-26 Sat 14:00>
<2023-08-27 Sun 13:00>

The task must be completed by a specified time.

A timestamp prefaced with the key word DEADLINE informs agenda that work is to be completed by that specific time. Like SCHEDULED, if the task is a TODO item, it will be displayed in the agenda timeline only if its state is not DONE.

A headline can have both a DEADLINE timestamp and one or more plain timestamps.

* TODO Pick up Bicycle 
DEADLINE: <2023-09-26 Tue 14:00>

The task repeats over time.

A task that repeats should be represented in Org as an appointment with a repeating plain timestamp. An example for an event that repeats M-F at 10:00 for 15 minutes every week is displayed below.

* Standup
<2023-08-21 Mon 10:00-10:15 +1w>
<2023-08-22 Tue 10:00-10:15 +1w>
<2023-08-23 Wed 10:00-10:15 +1w>
<2023-08-24 Thu 10:00-10:15 +1w>
<2023-08-25 Fri 10:00-10:15 +1w>

Some recommendations when defining an event to be rendered in an agenda view:

• Avoid using a SCHEDULED timestamp for repeated events.
• Avoid tracking status (in other words, turning the task into a TODO item) for a repeating task; such tasks are implicitly DONE at the end of the day.
  • Use org-agenda-add-note (in agenda view, keyboard shortcuts: ’z’ or ’C-c C-z’) to add an inactive timestamped note to track work done for that task.
  • In an agenda view, you can use the keyboard shortcut ’v-[’ to view a reference to the above note.

The task has a number of sub-tasks.

A task can be broken down into subtasks by either creating a hierarchy of sub-headlines or checkboxes. Tracking progress in a hierarchy of subtasks/checkboxes can be done using a progress cookie (’[/]’ or ’[%]’) in the headline. The following example below illustrates this.

* TODO Refactor Registration Screen [0%]
** TODO Refactor Identity [0/2]
*** TODO Refactor Username Field
*** TODO Refactor Password Field
** TODO Refactor Address [0/4]
- [ ] Street
- [ ] City
- [ ] State
- [ ] Postal Code

Note that a progress cookie will work regardless if status (example TODO) is tracked.

The task has a priority associated with it.

A task can be annotated with a priority using a cookie of the form ’[#<level>]’ where <level> can either be ’A’, ’B’, or ’C’.

* TODO [#A] Clean House

Note that a priority cookie can be used regardless if status (example TODO) is tracked.

Examples

This section provides examples of common tasks that can be implemented in Org.

A 30 minute meeting that is scheduled at 09:00 hours every MWF

A planning meeting that is held at 9am every Monday, Wednesday, and Friday should be implemented as an appointment. A timestamped note can be added to the task using org-agenda-add-note.

* Planning Meeting
<2023-05-22 Mon 09:00-09:30 +1w>
<2023-05-24 Wed 09:00-09:30 +1w>
<2023-05-26 Fri 09:00-09:30 +1w>

Pick up dry cleaning for an event on 2023-10-06

An event on 2023-10-06 requires one to wear formal clothes that need dry cleaning. For this task, use the SCHEDULED timestamp for when the clothes must be dropped off and the DEADLINE timestamp for when they must be picked up.

* TODO Pick Up Dry Cleaning
SCHEDULED: <2023-09-25 Mon 17:00> DEADLINE: <2023-10-05 Thu 17:00>

Note that upon completion, this task by default will not be rendered visible in the agenda view, however an inactive timestamp will be added to the task marking the time of completion. You can use the keyboard shortcut ’v-[’ to view this inactive timestamp in an agenda view. An alternate approach is to use the "l" keybinding to the command org-agenda-log-mode in an agenda view to view a DONE item.

1-on-1 with a Colleague

This task too should be implemented as an appointment using a plain timestamp. As it is not a TODO item, it will always show up in an unfiltered agenda view.

* Colleague 1-on-1
<2023-09-19 Tue 15:00-16:00>

Work on Issue Tracker Ticket

A common practice is to have a “shallow” copy of an issue tracker ticket as an Org task. Such tasks take over multiple days to complete, involving a) time that is planned beforehand to work on the task and b) time that is actually spent on the task. The following guidance is offered to distinguish timestamps between the two in Org:

• Use plain timestamps to denote planned time beforehand to work on the task. Do not use a SCHEDULED timestamp for this.
• Use clocking work time to denote time actually spent on the task. More detail on Org clocks is described below in the section Clocking Work.

Here is an example of an issue tracker ticket/task.

* TODO T-132 Fix Network Call
<2023-09-21 Thu 09:00>
<2023-09-22 Fri 09:30>
<2023-09-25 Mon 13:00>

Clocking Work

Org provides a means to track time spent on task that is referred to as clocking work time. There is rich behavior to how Org clocks work and it is highly recommended to study the documentation to understand its nuances. That said, clocking basic work time is straightforward to do, particularly from an agenda view.

Basic Clocking Operations

Clocking operations are easiest performed from an agenda view.

With the point placed on the task, the following keybindings related to clocking are available:

• I is bound to org-agenda-clock-in Starts the clock for the task.

• O is bound to org-agenda-clock-out Stops the clock for the task.

• l is bound to org-agenda-log-mode Shows the clock information for a task in the agenda view, among other org-agenda-log-mode-items. This mode is especially useful for seeing all clocked activity for a day.

Some guidance when working with Org clocks:

• Org clocks were designed so that only one task can be clocked at a time.

• Consider persisting the running clock and clock history over restarts of Emacs. Any state information related to clocking is lost upon restart by default in Org. To persist clocking state information you must do the following:

  1. Set org-clock-persist to persist the running clock and/or the clock history. Setting this value to t will persist both the running clock and clock history. Use describe-variable to see all legal values of org-clock-persist.

  2. Call the function org-clock-persistence-insinuate. This is typically done via org-mode-hook.

Closing Guidance

Described above are the different attributes Org offers to annotate a headline to represent a task. These attributes impact how the heading can appear in an Org Agenda view, if at all. While the reader is open to shape these headline attributes to what best suits their workflow(s), I have found the following guidance to minimize surprise when using an Org Agenda view to manage such tasks:

• A task (headline) does not need to be a TODO item to show up in agenda.
• It is best to reserve SCHEDULED only for a TODO item that does not repeat.
• Use clocking to keep track of time spent on a task.
  • Use org-agenda-log-mode in an agenda view to see the clocked record.
• If the TODO item requires work that crosses multiple days:
  • Use plain timestamps to reserve blocks of time to work on the task.
  • Use clocking to actually track the time you spent on the task.
  • Use org-add-note to add timestamped information to the task.
• Think twice before turning a task into a TODO item. Keeping it as a simple Org appointment is likely the better thing to do.

Addendum - 30 Aug 2023

An alternate to using a repeating timestamp is make copies of the same task. This addendum post elaborates more on this.

emacs   org mode