This is not a tutorial or guide to Emacs Org-mode. It is the journey of improving my workflow. If you wish to learn Org-mode yourself, look elsewhere.

Living in Markdown

I love Markdown. It’s versatile, yet so simple. I write all my notes in Markdown. This blog is written in Markdown. I have even made presentations in Markdown using Marp.

For several years now, I have had a file called This is a Markdown document where I keep track of things I am currently working on. It would always have a to-do list at the top, and that list would grow more and more over time. Many of the items directly corresponded to official Scrum tickets stored in our Scrum system. Keeping it in a Markdown document just makes it easier for me to work with. Other items are miscellaneous tasks I need or want to do, but which aren’t strictly in the plans. This could also be personal tasks like remembering to email someone or doing my monthly time reporting. I often add notes to the different tasks. Especially the ones I’m currently working on. I note down what I’m doing, edge cases I need to remember, and any other thoughts I have. This meant that a single task quickly grew in size, often to the point where I could no longer get a good overview of my tasks.

Now, let me preface by saying: this could definitely have been solved by other means. However, I had been eyeing Org-mode for quite a while and for other reasons also wanted to transition from Vim to Emacs, and so I took the plunge. Following this, I renamed the file from to

My newfound love for Org-mode

I have still kept the general idea and structure of the file, it is still a to-do list. The most impactful feature of Org-mode was collapsing/expanding sections and subsections. When I open up the document in the morning I get a nice view of all the major tasks that needs to be worked on. Some tasks will have long lists of subtasks, and some of those subtasks may have a few paragraphs of notes. The file is currently ~500 lines long. Any task that is completed is moved to an archive file, and if possible I like to summarize my findings in a proper document about that specific functionality to more easily refer back to in the future (as opposed to going into my jumbled mess of notes).

The second feature of Org-mode which got to me was the concept of the editor helping with managing my to-do list. It lets me declare which states I want a task to go through. I have this set as TODO, ONGOING, [MR], WAITING, and DONE. With the push of a button I can cycle through these states. When it reaches DONE it also adds a timestamp of the current time to indicate at what time I finished it. Automatic timestamping can be used on other states as well, if one wishes to do so.

[MR] means I have opened a Merge/Pull Request for the task and it’s waiting to be reviewed. WAITING indicates some external reason keeping me from working on it (e.g. a dependency on another developer to finish something first).

Having used this for a couple weeks now I feel much more Organized in my work. This doesn’t mean I’m abandoning Markdown completely (yet). I will keep writing this blog in Markdown, and probably any shared documents since markdown is much more prevalent and almost universally known by developers.

Future possibilities

If you want to be extremely rigorous in time reporting you can use Org-mode to keep track of the total time spent on each task. By marking when you start and stop working on each task during the day it can generate a report.

Org-mode has great support for exporting to other formats, like making presentations or writing academic papers. You can also run code from within code blocks inside Emacs, and have the results rendered when exporting to other formats. Hugo, which I use for creating this blog, also supports Org-mode natively.

There are certainly many more useful features of Org-mode that I have yet to discover. The possibilities are endless. I’m sure collapsing/expanding sections could’ve been done in Vim or any other somewhat capable editor. But I’m looking forward to making the most of what Org-mode offers.