On note-taking and command-line task management

Wed, Mar 11, 2020

A couple of years ago I began writing small notes to myself at the end of the workday. Notes that were meant to quickly get me back into “the zone” the next day. An example note could be:

You considered the method X in class A to be the source of that race condition, so you started writing additional tests in the branch Y. Remember to ask Peter about ideas since he worked on this part of the code last.

I kept these notes in a single append-only document on my computer: todo.md. Every morning I would open the document to get a refresher on where I left off the previous day. This worked well, but a few issues arose:

It could be difficult to choose which of the tasks from the previous day to pick up if there were multiple.
If I worked on multiple tasks during a day then I would have notes for each of them. Pushing multiple notes forward to the next day would lead to a mess in my notes file. Especially if there were tasks that lay dormant for multiple days.
The notes I wrote could get long. I discovered that I didn’t only want to store the “previous step”, as it were, but everything that I’d done and tried related to a task. More on the advantages of that later.

Enter TaskWarrior

TaskWarrior is a feature-rich task manager for your command-line. If you have not heard of or seen TaskWarrior in use, I encourage you to see this entertaining talk by Paul Fenwick:

There are many blog posts about TaskWarrior as well, in addition to the excellent official documentation. Here are a couple of good ones:

TaskWarrior solved the three problems I listed above:

TaskWarrior allowed me to put different priorities on different tasks so that I knew which ones were more important to pick up first.
I could now schedule when my notes/tasks should re-appear. This was handy if a task was waiting for a response from a third-party that would be back the following week.
I now used a TaskWarrior enhancement called TaskOpen to keep a note with each task.

What a life improvement! I would literally save milliseconds every single day. Still, after using TaskWarrior for a while I discovered that I had some (minor) issues with it:

Synchronizing tasks and notes across computers was not ideal. TaskWarrior comes with something called TaskServer, which I found unnecessarily cumbersome to setup. I ended up just using a Dropbox-folder as a backend. That was also a problem though, as I was not allowed to keep tasks related to some work projects on such a cloud service.
TaskWarrior is written in C++, a language that I’ve never worked with and have no immediate wish to learn. TaskOpen is written in Perl, a language that I really do not want to touch at all. If I wanted to see how things worked or to contribute to the projects, I would have to learn these languages first.
The process of taking notes was too cumbersome. First I had to create the task, then I had to annotate it with “notes”, and then I could actually open the note and start writing. Also, the notes themselves were not stored along with the tasks.

Enter dstask

By chance, I stumbled upon a new project a few weeks back: dstask. Its GitHub tl;dr states:

A personal task tracker designed to help you focus. It is similar to taskwarrior but uses git to synchronise instead of a proprietary protocol.

Now hey!

A git repository as a backend? That sounds a-okay. It would be easy for me to keep separate repositories for work and personal things.
dstask is written in Golang. I would have preferred something like Haskell or F#, but Golang beats Perl any day of the week.
Notes are built-in with dstask, and they are stored along with the task. No need for me to search in multiple locations if I wanted to dig back the specifics of a problem solved in the past.

Needless to say, I immediately gave dstask a try, and I ended up staying with it.

The author of dstask, Callan Bryant, wrote a blog post on why he created dstask that’s worth reading: Dstask, a Taskwarrior Alternative. There he explains his own qualms with TaskWarrior, and how dstask solved them.

Show me the money!

I won’t actually show you how TaskWarrior or dstask works. Others have done that job well in the past. Again, I’ll point to these:

YouTube: Manage all your tasks with TaskWarrior
Blog post: Taskwarrior, where have you been all my life?
Blog post: Getting Things Done with Task Warrior
Blog post: Dstask, a Taskwarrior Alternative

What I will do though is to list all the advantages that I see of excessive note-taking, and give some pointers on what to actually note. At the very end of this blog post, I’m also including an example note of mine.

Advantages of excessive note-taking

You’ll always know where you left off, and therefore where to pick up on a task. This allows you to get quickly back into the zone.
You’ll have a record of everything you’ve done. This is handy for several reasons:
- If you ever stumble upon a problem for the second time (which you will, I guarantee it), you won’t ever think “Oohh I’ve seen this before. What did I do back then to solve it?”. You’ll just reach for the solution in your notes.
- If a colleague needs the solution to a problem that you’ve seen before, you’ll have it ready. (Your colleagues may start thinking that you have a really good memory. It’ll be our secret that you don’t.)
- In case anyone ever thinks that you don’t work enough, just show them the record of all that you’ve done. When they see all those notes, they’ll never doubt you again.
- If you’re a consultant and your client wants a more detailed overview of the hours that you’ve worked, it’s easy to look back and see what you did.
- When a task is done, you’ll have a good view of what actually took time. Was is the task itself? Was it waiting for third parties? Was it some unexpected bugs that appeared along the way? You’ll have a record of it.
You’ll become a better writer.
You’ll become better at expressing yourself in general.
You’ll have tons of material for blog posts if you’re that way inclined. (I’m not, as you can see from my blog post count.)

What to note

A full detailed explanation of the task that you’re going to work on. You should include:
- Links to any task-management system like Trello or Jira.
- Your own interpretation of the task. Several times I’ve discovered that I didn’t really understand the task to begin with. By writing down my initial interpretations and assumptions, I’ve become better at sorting out misunderstandings earlier rather than later.
Details about any problems you stumble upon along the way. If you’re a programmer like me, this means stacktraces, lines of code, git commit hashes, links to possible solutions, versions of everything, etc.
The detailed solution to each problem. You’ll also note links to pull requests, build status pages, release pipeline pages, etc. And you actually write down things like: “I’ve hit the deploy button now, and now I’m going to monitor our dashboards while it’s deploying.”. If you’re suddenly yanked away from your desk for whatever reason, it’s nice to have those words there when you get back.
Installation instructions for any tools that you try. Write down step by step instructions for how you installed in on your system. Note the version of the program, the version of your system at the current time, the web page where you downloaded it from, and so on. If you ever need to reinstall everything on your computer, then you’ll have steps to follow to install everything you had before. I note these kinds of instructions in the note for the task while I’m doing them, but afterward I’ll also add the instructions to a instructions.md document where I keep instructions for everything.

Example note from my collection

The below note is a couple of weeks old, from when I wanted to try Eclipse Che again. It’s not a long note, but it’s a good enough example that shows my workflow:

# 05.03.2020

Starting point: https://www.eclipse.org/che/docs/che-7/running-che-locally/

13:45
- You're working on installing minikube:
Instructions from <https://minikube.sigs.k8s.io/docs/start/linux/>:
1. Download and install: `curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64 && sudo install minikube-linux-amd64 /usr/local/bin/minikube`
1. Verify virtualization support: `egrep -q 'vmx|svm' /proc/cpuinfo && echo yes || echo no`
- You're workign on installing virtualbox
Follow instructions from https://www.virtualbox.org/wiki/Linux_Downloads:
1. `sudo add-apt-repository "deb https://download.virtualbox.org/virtualbox/debian bionic contrib"`
1. `wget -q https://www.virtualbox.org/download/oracle_vbox_2016.asc -O- | sudo apt-key add -`
1. `wget -q https://www.virtualbox.org/download/oracle_vbox.asc -O- | sudo apt-key add -`
1. `sudo apt update`
1. `sudo apt install virtualbox-6.0`

14:02
- Installing chectl
https://www.eclipse.org/che/docs/che-7/installing-the-chectl-management-tool/
To install: `bash <(curl -sL  https://www.eclipse.org/che/chectl/)`
Verify installation: `which chectl` and `chectl version`

14:06
- Installing helm
Instructions from <https://helm.sh/docs/intro/install/>:
1. Download Linux amd64 from <https://github.com/helm/helm/releases>
1. Untar `tar -zxvf helm-v3.1.1-linux-amd6`, this will give you the folder "linux-amd64"
1. `sudo mv linux-amd64/helm /usr/local/bin/`
1. `helm version` should work and show you the version

14:08
- Start minikube and use chectl on it
1. `minikube start`
1. `chectl server:start --platform minikube`

14:35
- You were able to start che, but when trying to create a workspace (spring boot with the petclinic demo) the pod wasn't able to start due to insufficient memory.
- Trying again, now with more memory.
- `minikube start --memory=4096`
- `chectl server:start --platform minikube`

When doing `k -n che-che describe pod xyz`, the last line still says
> Events:
>  Type     Reason            Age        From               Message
>  ----     ------            ----       ----               -------
>  Warning  FailedScheduling  <unknown>  default-scheduler  0/1 nodes are available: 1 Insufficient memory.

You may have to do `minikube delete` for the new memory allocation to actually be used.

Trying again
- `minikube start --memory=8192`
- `chectl server:start --platform minikube`

14:53
- Now you've come further, to where the docker images for maven++ are being pulled inside che. You think that the workspace will actually be created this time.
- Most recent logs from with <http://che-che.192.168.99.101.nip.io/dashboard/#/ide/che/java-web-spring-m10bg>:
    ```
    Saving log of installed plugins
    All plugin artifacts have been successfully downloaded
    Pulling image "quay.io/eclipse/che-java8-maven:7.9.0"
    Successfully pulled image "quay.io/eclipse/che-java8-maven:7.9.0"
    Created container tools
    Started container tools
    Pulling image "quay.io/eclipse/che-sidecar-java:8-0cfbacb"
    Successfully pulled image "quay.io/eclipse/che-sidecar-java:8-0cfbacb"
    Created container vscode-java39c
    Started container vscode-java39c
    Pulling image "quay.io/eclipse/che-machine-exec:7.9.0"
    Successfully pulled image "quay.io/eclipse/che-machine-exec:7.9.0"
    Created container che-machine-execxgz
    Started container che-machine-execxgz
    Pulling image "quay.io/eclipse/che-theia:7.9.0"
    Successfully pulled image "quay.io/eclipse/che-theia:7.9.0"
    Created container theia-idet0b
    Started container theia-idet0b
    ```
- The next line to appear was this error: `Error: Failed to run the workspace: "Server 'theia' in container 'theia-idet0b' not available."`

14:57
- Trying again to start the workspace
- You get quickly to "Started container theia-idefu2", but there it stops. It will probably end with the same error again
- The logs for the container theia-idefy2 (`k -n che-che logs -f workspace8t3oop3dqb6wkl5x.tools-7d45bc8747-kvvk8 theia-idefu2`) has this as the last line: "root INFO Deploy plugins list took: 3804.4 ms"

15:17
- Created a github issue: <https://github.com/eclipse/che/issues/16244>
- `chectl server:stop`
- `minikube stop`

---

# 06.03.2020
You got help on [the issue you posted](https://github.com/eclipse/che/issues/16244)! Trying again now with the operator.
- `minikube start --memory=8192`
- `chectl server:start --platform minikube --installer operator`

You have to create a user now and login, but after that - it works!

Hopefully, this has helped convince you to use either TaskWarrior or dstask, and to take more notes while you work. Carry on!