Literate Doing, Write everything you do              

  • Post by Maxime Cote
  • Feb 07, 2020

Over the past couple of weeks, I’ve been experimenting with a pretty exciting idea I came across. It’s in the same family as “writing with a pen in hand.” I would also it has some similar benefices. I will call it literate doing here for this article. Mostly since you could replace “doing” with just about any job where you do experimentation. Programming, DevOps, Security, Science, all those require testing and problem solving and could benefit from being “literate.” But what is this “literate” and how can you use it.

Write, write and write

The idea is simple, yet not that obvious at first. Just write what you’re doing, maybe the reasoning and the result, and then repeat with the next steps. The exact details will depend on the field, the reason, and the project itself. For myself, I found that the main idea, how to do it, and the results are enough for most projects. Here’s an example:

- Trying to debug new server problem with NTPD
	- Look if the service is running correctly
		- it was running
	- Examining if the NTP servers are setup

You can also use this text to put down tasks and questions you thought about while working. The best is to give them some tag or a pattern to find them back. Writing them like that will prevent you from breaking the flow of work since there’s no context switch. Then every so often, filter the note for TODO and add them in your todo list. That’s pretty much the full technique really, but why would you do that?

Write what you think and think about what you write

The primary benefit of literate doing is helping you to think more clearly. That’s also very similar to my writing as you read article. Writing what you’re currently trying will give you an idea of your current understanding of the problem. Do you have trouble writing it down as you go? Then you might not fully understand what you’re trying. It might be that you’re missing clarity on the next step, research, or understanding. This lack might be correct if you’re doing research, but it could also be the sign of a problem. So forcing yourself to write down, even just one sentence is an excellent reflection of your current state. And, just like taking notes while reading, it will make you more focused and more aware of your ideas and connection.

Intermediate Packages

Another great reason to write everything you do is that it creates intermediate packages. That term and idea come from Tiago Forte in Building a Second Brain. The idea is to create “snapshot” or “packages” in a project at various points. Those snapshots allow for faster feedback and re-usability of parts in the future and also helps with context switching. Those intermediate package, in turn, serve to create a much shorter ramp-up to reach flow since you don’t need to remember everything you did. If you took the time to write down your ideas and steps already, then you have a package done. You can put the project on pause (of your own decision or not), then come back later and pick it up exactly at the same spot. Since you have all your previous thoughts, steps, and experiments right there, you only need to scan them, and you’re ready.

Those intermediate packages can also be shared to some extends with others. If you happen to need help from someone or get feedback on the progress, those could be useful. It should be far easier for that person to help you with something if they can quickly see what you tried. Just be warned, I would suggest you copy-paste only the central part if you plan on sharing it. The main reason for that is you will most likely generate a lot of text. Then a person helping you might not have time to go through hundreds or thousands of lines to see the problem. Another reason is the way you organize that file will be personal to you and how you think. That can be unclear to others, and they would need to try and understand how your train of thought works. Just be mindful and help them help you.

How? Won’t that slow me down?

Not with tools made for that purpose. They’re not mandatory, but I found out outliner tools works wonder with literate doing. Outliners are editor that allows you to collapse, zoom, and show text based on a hierarchy of bullets. Usually, that hierarchy is tree-like with parents and children bullets and free-form otherwise. From there, you can expand, collapse, and zoom on the part of the document, so you focus on that one. Since literate doing will produce a lot of text, being able to focus on a section only is critical. Not having predefined structures is also significant at letting you work and organize as your brain wants.

One of those outliner tools is Emacs with its org-mode. I recently got back into using it as my primary text editor, and org-mode was one of the big reasons. That mode is one of the best outliner tools I came across, but not the most user-friendly or straightforward. One of its strengths is that it works with a text file, which makes it portable and cross-device. From inside Emacs, with the help of emacs-lisp, you can also customize it to your own needs. Other notable apps I’ve tried that do a great job are Workflowy, Roam, RemNote. Those, for the most part, are more user-friendly but, in turn, have other limitations. I would suggest looking into them and giving them each a try to see which fit more your style and budget.