# Introduction Org Mode Project Management

I was asked recently about how I use Org Mode to organize my research. In this post, I will discuss some Org Mode generalities and in a subsequent post, I will focus more on research specific customizations.

# What is Org Mode?

Org Mode is a major mode for Emacs and is currently part Emacs. However, it is updated independently so newer versions are often available. According to the Org Mode site:

Org mode is for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system.

It started life as an organizer/outliner by Carsten Dominik in 2003 and has since grown in popularity. Org mode can be used to create spreadsheets, LaTeX documents, TODO lists, hyperlinks (both internal and external), and more. All of this is done with plain text, so any text manipulation tools can interact with .org files. You can also access the files with any plain text editor if you do not have Emacs and Org Mode available.

I use Org Mode to:

• keep my calendar
• track my time on projects
• organize and document research
• write scientific papers
• write conference presentations
• prepare lecture slides and notes
• maintain grade books for courses
• write and document code (mostly Python, but other languages to a lesser extent)
• and more…

Any text-based task I work on likely started in Org Mode and then moved elsewhere if necessary.

# Project Organization

Org mode has an agenda dispatcher which generates views based on agenda files. Agenda files are Org Mode files that you designate either through elisp in your initialization:

(setq org-agenda-files
(file-expand-wildcards "~/orgmode/*.org"))


This syntax sets all .org files in the orgmode directory to serve as my agenda files. As an alternative you can manually add a file to the agenda with <C-c [> or whatever you bind to (org-agenda-file-to-front). My current agenda files include:

admin.org
development.org
personal.org
proposal.org
refile.org
research.org
service.org
teaching.org


Org Mode parses these files to build your agenda calendar views. For example, my standard agenda for today (accessed by <C-c a a>) looks like:

Deadlines (or past due items) show up in red. Tasks that have been closed out are highlighted green. Meetings or blocks of time that are included in the agenda files show up on their respective days and the current day is expanded to show 2 hour blocks of the current day, along with a now indicator to show where you are in your schedule. The agenda does not show all your logged time by default, but you can show your clocked time by pressing <v l> in the agenda window to open the log view. Pressing enter with the cursor over one of the items listed in the agenda will open up the corresponding .org file to the event location. You can export the agenda calendar with (org-icalendar-export-agenda-files) and then load them into applications that read .ics files (this is how I maintain my Google calendar on my webpage).

Org Mode has a number of standard agenda views that require no additional configuration. These includes ways to filter your TODO lists, matching tags, timelines for single files only, and more. It is also possible to create custom agenda views, but that is beyond the scope of this introduction.

## Agenda File Structure

My agenda files all have a similar structure. Top level headings usually have broad scopes and are mainly used for organization, while second level headings and below are where I create tasks and track my time. You can set times on any heading (Meeting today from 10:00-11:00), add deadlines (Project due: 8-27-2015), have repeating dates (Class on Mondays 13:00-14:15). Here is an example agenda file:

The dates in <> under the Classes headings are active time stamps. This allows the agenda parser to add these dates and times to any agenda view. The +1w at the end of the specification schedules that block every week. The NEXT keyword lets me know that this is an active TODO item that I have started work on. The DONE keyword is for a task that has already been completed. On the right hand side of the heading are any tags that have been set. In this buffer, I have two tags displayed: :instruct: and :InsSup:. For my own reporting, I need to know how many hours I spend giving instruction and how many hours I spend supporting that instruction; these tags help me track that information. The :LOGBOOK: underneath each heading contains the time I have clocked in on each task. By default clocking in to a task is bound to <C-c C-c C-i> or (org-clock-in).

How you end up organizing your agenda, both the types of files you include and the content of those files, is largely a matter of preference. I usually make some changes to my agenda set up every semester as I figure out what things work well for me and what does not. While my setup does have some customizations (which will be the subject of another post), virtually all of what is shown here can be done with a default Org Mode installation.

# Recommendations and References

If you are interested in using Org Mode either as an outliner for notes or for project management and tracking, I encourage you to just jump in and start using it. Just about all the functionality in Org Mode is optional: it does not affect you if you do not use it. Trying to use all or even most of the Org Mode functionality as a beginner can be intimidating so start small with simple tasks and work your way up from there.

If you only want to outline some of your work, use headings to give your work some structure and type the remainder normally. You can completely ignore all the time tracking, deadlines, tags, or agenda functionality with no trouble. If you decide to expand your scope from outlining to keeping some important calendar dates, simply add an agenda file and set either an active time stamp or a deadline. As you get more comfortable using Org Mode, you may decide to expand your work flow to include more and more task, using more and more of Org Mode’s functionality.

Org Mode has an active community, many of whom are creating tutorials and videos about Org Mode. If you are not sure about using Org Mode, I recommend viewing the general introductions to Org Mode that can be found among the tutorials collected on the Org Mode site. For those looking for more customizations, there is a section where power users describe their setup. When I was looking at tweaking my own setup, I relied heavily on Bernt Hansen’s Organize Your Life in Plain Text! and I still use large portions of his configuration.

1200 words