.plan files

A couple of years ago I was reading Masters of Doom, and something that really struck me was how programmer John Carmack used to keep track of his daily work: .plan files. Now, there are a lot of resources online covering what .plan files are, how to access them, or even what John Carmack's .plan file looked like, so I am not going to talk about that; what I am going to talk about is how I started using .plan files and the workflow that I have developed around them. Before that though, let me first spend a few words on the reasons why I think people should start using .plan files again (or at least, similar solutions).

Why

First things first, it's simple: a plaintext file, few syntax rules, public availability, and that's it.

Second, keeping my .plan file up to date helps me staying organized. Did you bump into something you want to fix, but don't have the time to do it now? Add an entry for it. Did you find an interesting article to read...later? Add it to your .plan file. Did you spend a lot of time debugging a problem? Write about it, so that you can come back to it later, should something similar happen again. It's like your digital, personal journal.

Lastly, keeping up with your .plan file is going to help improving your technical writing skills, and especially if you work in the same industry as I do, you know how important that is (e.g. document things, file clear and descriptive bug reports, or describe solutions to technical challenges).

Format

The format of my .plan files is pretty basic: mostly based on John Carmack's early .plan files, with just a bit of Markdown flavour in it.

Usually the first few lines of all my .plan files will tell you what the file is about, and give a bit of an overview of how the file itself is structured. For example:

This is my .plan file ...

When I accomplish something, I write a * line on that day.  Whenever a bug
/ missing feature / idea is mentioned during the day and I don't fix it, I make
a note of it and mark it with ?.  Some things get noted many times before they
get fixed.  Occasionally I go back through the old notes and mark with a + the
things I have since fixed, and with a ~ the things I have since lost interest
in.

Sometimes I rant about broken things (mostly, computer related), and how I go
about and (try to) fix them.

--- Matteo Landi

The careful reader might notice that this welcome message is very similar (90% similar) to what John Carmack had in his .plan file back in the 90s; just a few tweaks , to make the file a bit more Markdown friendly (~ instead of - for things that I have no more interest in, or prefixing my todos with ?). I don't explicitly tell how day entries are implemented but at least the reader knows there will be some (and it should be pretty straightforward to understand the structure, once they go through the file).

Speaking of day entries, in my .plan those are implemented as Markdown's sections headers (with the specific date in it), and anything that happened on that day will go right below it:

# 2020-05-12
Did a little bit of debugging as to why **all** my Common Lisp Windows
executables were not printing things out on the stdout as expected, and it seems
to have something to do with redirection...
...

# 2020-05-16
Alright, I think I figured out what I had to do in order to get my CL programs,
on Window, to properly output stuff to stdout.  It turns out you have to
explicitly tell deploy[1], the system I use do deploy standalone CL
applications, that you want your Windows application to be a _console_
application, or otherwise deploy will go with a GUI application (and GUI
applications that don't usually get a standard output to write to).
...

And if for a given day entry I end up writing about completely unrelated topics, I would simply stick a --- separator in between, and create two or more sub-entries:

# 2020-05-16
Alright, I think I figured out what I had to do in order to get my CL programs,
on Window, to properly output stuff to stdout.  It turns out you have to
explicitly tell deploy[1], the system I use do deploy standalone CL
applications, that you want your Windows application to be a _console_
application, or otherwise deploy will go with a GUI application (and GUI
applications that don't usually get a standard output to write to).

[1] https://github.com/Shinmera/deploy

---

Run into another problem with Travis-CI the other day; when deploying artifacts
to GitHub, it would error out with the following message:

    /home/travis/.travis/functions: eval: line 109: unexpected EOF while looking for matching ``'
    /home/travis/.travis/functions: eval: line 110: syntax error: unexpected end of file
...

And that's pretty much all you need to know to process my .plan file; knowing a little bit of Markdown would not hurt (e.g. emphasis, strong, code, links), but Markdown is simple enough that you can figure things out as you read it.

Personal setup

I don't have a single .plan file, but multiple of them. My personal one for example (also publicly available here), is where I write about things that I have to get done (or have already gotten done), projects I started working on, ideas, or computer-related problems I am dealing with (and their solutions once I figure them out). Then I have another .plan file that I use at work: very similar to my personal one, but all about work-related stuff. At work, I also keep different .plan files one per each person working in my team and reporting to me, and mostly use these for 1-1s minutes, or for big achievements / projects that these people completed throughout the years.

All my .plan files live in Dropbox, and since I have Dropbox installed on all the PCs I care about (even on my mobile phone), I can edit all my .plan files from everywhere. Of course you don't have to use Dropbox, but I just find it too convenient for not using it: edit your .plan file while on the go, hit save, and when you get back to your PC the added content will be there; or the other way around, you shut down your PC, hop on a train, you open Dropbox on your mobile, and a few seconds later you can continue working from where you left off before. Of course I don't have this urge of editing my .plan file every time I am on the go, but if I have to, I can do it.

Talking about editing .plan files... I use Vim as text editor, and if you do too here are a few tips / hacks to make ".plan files editing", even more enjoyable:

A syntax file to color basic things like day entries, todos, emphasis, strong, links, and code (to be placed at ~/.vim/syntax/plan.vim)
A folding file to create folds for day entries (to be placed at ~/.vim/ftplugin/plan/folding.vim)

An autocmd group to create mappings for creating new day entries without specifying the current date, or to automatically populate the quickfix with all the todos listed in the .plan file being edited:

augroup ft_plan
    au!

    au FileType plan setlocal wrap textwidth=0
    au FileType plan nnoremap <localleader>n Go<cr># <C-R>=strftime("%Y-%m-%d")<CR><CR><BS><BS>
    au FileType plan nnoremap <localleader>o :silent lgrep '^\?' %<cr>:lopen<cr>:redraw!<cr>
augroup END

Lastly, I have a cron(8) job on my server, that every night downloads my .plan and places it into a specific folder so that my web server can serve it. I also wrote a small program, plan-rss, that my server automatically runs to create a RSS feed of all the most recent day entries of my .plan file (it's not perfect, but if you are looking for a way to stay up to date with my .plan file, then subscribing to my plan.xml is probably your best bet).

Closing thoughts

That's pretty much all I had to say about .plan files, and if anything, I hope I made you at least a little bit curious about the idea behind them.

Remember: it does not matter which syntax rules you end up using, which editor you will be typing these notes in, or which mark-up language rules you will ultimately end up supporting. What really matters is that you start writing, and start taking notes... and more importantly, that you do this consistently: the more you do it, the more natural it will feel, and the more weird it will feel to get at the end of the day, after having spent so many hours in front of your PC, without having created an entry in your .plan file.

Happy .plan-ing