Things I Learned in 2020

   Internet

Let’s get the elephant out of the room: 2020 has been a very different kind of year because of the COVID-19 crisis. I am very fortunate that myself, my wife, our family and close friends have not been – so far – impacted in any meaningful way.

However, this blog post is not about COVID-19. In fact, I have been thinking of doing some kind of the yearly retrospective for the last couple of years. So here I am, starting one now, and trying to leave the COVID topic aside.

I do read a lot of development blogs. My interests in programming languages and technologies are varied and somewhat eclectic. The blogs I read range from the serious and in-depth analyses to more light-weight off the cough testimonies. Oftentimes, this is how I stumble on some interesting tool or a piece of technology which I may end up using months or years later. I am writing this blog post with the hope that it may be useful to someone else in the same manner.

TL;DR

So here are three things I have learned in 2020: Terraform, Notion and I somewhat improved my writing skills.

Terraform

I had been aware of Terraform for some time. It is a tool born of the infrastructure as code methodology from DevOps. Unlike older solutions, which were historically rooted in imperative scripts such as Chef or Puppet, Terraform only supports the declarative approach. In other words, you describe the end state of the cloud infrastructure you want, and Terraform figures out which steps are necessary, if any, to bring the system in line with expectations.

Terraform is a cloud agnostic tool. I did not need a multi-cloud tool, so I had reservations in adopting Terraform over a first party solution like CloudFormation for AWS. Both tools play the same role and are declarative, but CloudFormation being a first party product, it has the advantage that it integrates better with the AWS stack. The reasoning is correct, but what I failed to appreciate is how poor and painful it was to use CloudFormation in practice. Terraform provides a much better experience:

  • The description language of Terraform is less verbose and better designed than CloudFormation’s. It feels like Terraform was designed to be read and written by humans, whereas CloudFormation looks like a memory dump transcribed into YAML or JSON.
  • The documentation of Terraform is excellent despite being a third party provider. Not that the AWS documentation is bad either.
  • The killer feature of Terraform is the ability to refactor re-usable code into modules. This is a very straightforward and well-documented process. It compares infinitely better to the kind of hacks one would have to do with CloudFormation to achieve similar results.

One of the drawbacks of Terraform is that the current state of the infrastructure is stored on a file locally, whereas a first party solution like CloudFormation can store the state in the cloud. Personally, I like having the state in a GIT repository and I find it somewhat reassuring.

I currently use Terraform to use all my AWS resources: Route 53 DNS entries, EKR Docker Registries and a handful of Amazon S3 buckets.

Notion

I have been looking for a tool to take and organize notes. One of the many requirements was that the tool needed to be truly cross platform with support for macOS, Windows and iOS and features cloud syncing. In addition, I wanted a tool which can integrate very well with Markdown.

I essentially use Notion to collect links and information when I research a topic and to write design documents. I also adopted the practice of scientists who keep logs about their work. The draft of this blog post was also written in Notion first, before being exported as Markdown and published via Hugo.

I have been looking for a good note taking tool since 2019. I have looked at many and tried a handful. Even though I was aware of Notion for a long time, I was somewhat put off by it. I understood it could be used to publish things on the Internet and it had some kind of database features. Those features are not exactly something I cared for, so they acted as repulsive force, because I was worried about feature creep and unnecessary complexity. These thoughts were echoed by CGP Grey from Cortex; so Notion was put to the back of the pile. How wrong was I!

The truth is that Notion is still a pretty good way to take and organize textual notes. All the normal features from a Markdown editor are well supported, including syntax highlighting for code snippets, even though it uses a WYSIWYG editor. There are some useful additional features like the ability to use Callouts, Emojis or insert LaTeX formulas. The import and export of Markdown is not perfect but it is usable. I have used some of the advanced features like tables, databases and calendars and they are fine. The ability to publish a note as a public webpage on the Internet in one click has turned out to be surprisingly useful, especially since that page automatically updates when the source document in Notion is updated. And to top it all, it looks like my usage of the tool would fit in the free tier forever.

Although I am overall satisfied, Notion has some usability annoyances. Non standard key bindings and mouse control for text selection drive me mad. Occasionally, the WYSIWYG editor will require some non obvious combination of key strokes. But the main downside, by far, is that I am not in control of the data. The way information is stored on the file system or on Notion’s servers is completely undocumented. The Notion API was successfully reversed engineered, but an official Content API should be launching in 2021. Until then, it seems like the official way to backup data is to Export the Workspace as HTML or Markdown, but it is a lossy export. I am currently relying on exports but I hope to start using the upcoming Content API when it becomes available.

Notion’s Alternatives

While researching a note taking tool, I stumbled on Bear. It provides a native editing experience that I like more, but fewer features than Notion overall. The downside is that it is only supported on iOS and macOS (no Windows / no Web). But if that’s not a deal breaker, it is an excellent tool. I also stumbled on Typora which is a very good Markdown Editor, that I use regularly with the Ursine theme. I don’t use Notion’s project management features very much. For very simple lists of things to do, I tend to rely on the much simpler Microsoft To Do.

Improved Written Communication

I have worked from home for most of the year. Even though there are some obvious advantages like avoiding the daily commute grind, the lack of face to face communication has many drawbacks that cannot be fixed by video conferencing.

One of the obvious consequences is that all but trivial communications (which can be done via instant messaging with tools like Slack) must be formalized into a meeting or an exchange of e-mails. Consequently, I have found myself reading and writing more prose than ever before.

The trick with written communication is that you need to be as clear and non-ambiguous as possible while remaining concise. Clarity is very important. If one of your colleagues were to misinterpret one of your ideas, you an easily end up exchanging a few e-mails just to clear things out. This translates into wasted time, and some frustration, for everybody involved. If you had been in the same room, you would have been able to intervene sooner and save that time. Making things clear can involve some amount of repetition or rephrasing, or showing examples. Whenever possible I try to show a diagram or a table instead of prose.

The goal of clarity needs to counter-balanced by the necessity to be short and concise. Long and winding emails are boring to read, so people will just skim them or put them off until the last minute. I know, I am guilty of the same thing. For communication to have an impact, it needs to be read, therefore it needs to be short.

Through repetition, I would like to believe that I have somewhat achieved a basic level of competency at written communication. I am better at it than last year, and definitely better than ten years ago, as plainly demonstrated by the earliest – cringeworthy – posts on this very blog.

As an aside, I would like to recommend “Have You Eaten Grandma?”, a book which is very humorous way to review the basic rules of grammar and punctuation in British English. (Yes this blog is written in American English except for rule about punctuation within quotes or brackets.)