Taking Technical Notes – An undervalued IT discipline.

A challenging idea: Take notes for every significant thing you do with your IT infrastructure

Upon seeing the statement above, some people will be concerned about the time cost of taking notes for everything. Some may object that there is only the possibility that any time spent taking notes will be returned or rewarded later down the track. Considering how the human mind is wired to have a better grasp of short-term than long-term consequences and that the future benefit of having notes is, to some extent, speculative, this is understandable.

While technical notes can be no more than a record of things that happened, they should also be considered a recipe for repeating or improving future processes. Information from reliable and accurate notes can also be retained as part of site documentation, included in the training, or used for planning changes. All of these processes will take more time in the future if notes are not available.

Documentation alone is widely considered an important skill for IT professionals to cultivate^{1 2 3 4 5 6}. However, even if many notes never contribute to documentation, there are still good reasons to maintain the habit of notetaking, not only for maintaining existing infrastructure but also for the aspects of personal discipline and practice of documenting processes.

Notes for Critical Circumstances and Future Uses

Many of us fail to cultivate the habit of taking reliable notes until some tipping point, and often it’s due to a particular type of technical emergency. There can be a system problem where others rely on you to do your work quickly and accurately. Perhaps an issue where you even said something like, “Yeah, I have seen this before; I should have things running properly in a few minutes”. Often this can be true, but there are situations when solutions are not applied as quickly as promised.

Perhaps this time, you have missed a crucial step in haste, or it could be that a script you modified on some prior occasion has now hit unexpected input. Without notes on what you saw before, what you changed, why you changed it, or other reliable information from the prior work, it can be guesswork and repetition of whatever you can recall under pressure. It is possible that your day may quickly become quite awkward.

While we should all be aware that memory can be a very weak repository of information, it seems strange that it is so frequently the only repository for particular knowledge about IT infrastructure. Long-term memory should not be relied upon as a primary source of truth for any organisation. Taking notes as soon as practical seems more sensible. Memory is no good to anyone in the long run, especially when key individuals are not available in the organisation at times when their memories and experience are required.

Even a sole operator should keep good notes. Their memory may be great, but businesses do expand, and someday it may be worthwhile to assign particular tasks to others. Any new employees or contractors will need to quickly understand how your IT environment is organised and how to update or maintain it without the business losing access to vital services. Without documentation or notes, there is no practical way to unload many site-specific tasks to a new employee quickly, however skilled they are. All alternatives to written information will take more time.

In the short term, there will be days when the owner must attend to matters away from their usual business operations. If they have all the right pieces in place ahead of time, they may want to assign someone else to maintain the business for a short while. Although it may not be economically viable for them to do so in the early stages, there should be plans in place to ensure it is possible in the future. Perhaps, eventually, a vacation may be possible… who knows. The first step is to get important infrastructure details down in writing in a systematic and disciplined way.

My experience with Evernote

I feel that my excuses for not taking notes under particular circumstances generally go down to issues with the available tools. Until the last few months, I have been an Evernote user for over a decade.

Evernote is a great general-purpose tool, but creating and maintaining technical notes, including scripts, code, logs, or tabulated CLI output segments, was awkward. For these uses, I felt that Evernote really is no better than something like Google Keep. At least Google Keep syncs to any number of devices and is free and lightweight.

I found some functions in Evernote to be awkward or limiting, so I stopped bothering with it while on the run. This is not an ideal strategy. On those occasions, I may voice-to-text a Google Keep note to remind myself to write up the details in Evernote later. Occasionally that reminder might stay in Google Keep until after the facts about the issue had faded in my mind. At that point, any accurate outline of the matter would require revisiting the incident in depth.

With Evernote, while there were times that the limitations of the free plan would be an issue, this did not occur often enough to warrant an ongoing paid subscription. There was always the consideration that Evernote was already failing to meet my needs in many material ways; paying for it did not add up.

Again, I am not putting down Evernote, only reflecting on how the product’s functionality was not a good fit for my particular uses. Many people are quite dedicated to Evernote and have been using it happily for years with few significant issues.

However, those and other limitations discouraged me from working with Evernote in many circumstances. I found I was no longer adding or updating notes as much as I should have been, and as a result, I was losing valuable detail in my work. My personal debriefs (which is how I view my note-taking) were becoming patchy, incomplete, and not as well organised as they could be, and this had begun costing me more time than it should have.

I decided to look at other notetaking applications. Honestly, I only tested about two or three others before I gave Joplin⁷ a try, and it seems to be a far better fit for my work than Evernote.

About Joplin

Joplin is an open source⁸ notetaking app that offers all the integration and editing features I need. It’s available on the mainstream platforms – Windows, MacOS, Linux, iOS, and Android.  There is also an AppImage that operates correctly on ChromeOS (voice-to-text notwithstanding).

Like the Evernote approach, Joplin also has a web clipper plugin for Chrome and Firefox, which I occasionally find useful.

I do not intend to go through all the pros and cons of Evernote vs Joplin; plenty of others have already covered that material, and I find those types of comparisons can only give a general idea of suitability. Beyond that point, we can only know if a particular application suits our purposes by working with it.

What follows have come of my findings based on the use cases specific to my needs and workflow.  These have been the significant factors influencing my switch from Evernote to Joplin, followed by a few drawbacks. I hope they are helpful to others. This is just a reflection on personal experience in no particular order.

My experience with Joplin

Imports

Joplin will import Evernote export files, so bringing in your Evernote repository takes only a few minutes. If anything is stored in Google Keep, I understand using Google Takeout to download any notes is simple. In my case, I made a text dump of all my Google Keep notes into a single text file and put them into a Joplin document. I have since done the work to convert my old Keep reminders into proper notes.

Sync Freedom

For my purposes, one of the major selling features is the ability to sync notes to (one of) several options, both self-hosted and commercial⁹. So far, I have synced to a self-hosted Nextcloud location and DropBox. I have been happy with both, occasionally switching between them based on need.

Some control is also available for automatic sync frequency and the option to turn off auto-syncing. This is sometimes handy when I know I will be offline or bandwidth is limited, and I would prefer to initiate syncs manually.

Unlimited devices

Last I checked, the Evernote free account is limited to two devices. With Joplin, I have all my devices syncing notes happily.

Layout

While notes can be added without tags or formatting, I usually work with standard Markdown with a few HTML5 tags to improve readability under some circumstances, which gives me the results I am interested in. The details/summary¹⁰ tags function correctly and give collapsing fields; we sometimes like to hide important but seldom-referred-to detail or log output.

Of particular importance for the way I like to write is Markdown footnotes. It is not mentioned in the documentation as far as I can tell, but Markdown footnotes are supported with an option that can be toggled to enable them.

Other options I have not yet used include Markdown options for writing math, chemical equations, and diagrams. Still, using these Markdown Extras in notes can make them less portable to other Markdown interpreters, which may not support those options, at least in the same way. You can enable your preferred subset of Markdown Extras in the Markdown preferences. More information can be seen toward the end of the Joplin information on support of Markdown https://joplinapp.org/markdown/

Dark Mode and Theming

Evernote offers one each of light and dark, which was enough for me while I was using it.

Joplin offers more kinds of light and dark options, which is a nice touch. You should take a look. For some reason, I have discovered that having multiple dark and light modes options in my notetaking app makes a difference for me.

Search

The contents of the notes are searchable. Tags can be added to notes. Location information can be included.

These are really no different from Evernote but are worth mentioning since they are expected functionality as part of a useful notetaking application.

Comfortable for Code

Regarding the availability of common functionality in Markdown (including a subset of “Markdown Extra” extensions), code syntax highlighting, vim/emacs keybindings, an option for auto-pairing quotes and braces, and the ability to cleanly integrate Joplin notes with VSCode, made Joplin a great way to handle my code snippets, and working with code blocks has become very quick and easy compared to my experience with Evernote.

Setting up the integration of Joplin and VSCode is not tricky, but I may document it here in a brief future post.

Linking notes

Joplin offers a very simple and clear way to create links between notes. While links are only unidirectional, the method for creating a link is so quick that adding a second backlink to the referring document takes only another moment. I have only tried this on the desktop version; I guess I have never tried it on mobile devices.

Note versioning and folders

Along with maintaining a note history, so you can roll back to a previous version of a note if required, there is the ability to place notes in hierarchical folders. It seems that moving notes into folders is currently only available in the desktop versions, but this is expected to come to the mobile versions soon. I believe the mobile app is more suited to reading notes and making small changes to existing notes.

Security

For security, Joplin offers encryption for your notes. Though I have not used it, it’s good to know it is available.

Overhead

The Joplin application seems more lightweight than Evernote and offers a feature set closer to my needs, so this may be a win both ways. It seems to do more for my workflow with less overhead than Evernote.

Joplin Caveats

The pros and cons of using Joplin vs using Evernote are documented by others elsewhere^{11 12}, so this is only a list of the things I find inconvenient in my work.

Others may find, for example, Joplin’s lack of collaborative editing is a dealbreaker. It’s not an issue for me, so I am not listing it (I guess I just did).

For the most part, the issues seen in Joplin have the attention of developers, and we should expect solutions to be coming in the future.

Images in the Android version

As of writing, the version I used on Android had issues with notes containing images larger than 10MiB. Generally, notes should not need to contain images so large. However, if you want to take a quick picture of some details and include them in a note while you are on the run, a 10MiB size limit is a gotcha that can slow you down when using a mobile device.

This issue seems to have been recognised, and a fix is being worked on.

Filing notes on the Android Version

As mentioned before, as of the time of writing, it seems this is not possible.

You can make notes, but they cannot be assigned to a note folder. It’s not clear why this is, and it can be annoying. I have reason to believe this may change in the future.

WYSIWYG Editing

Some types of editing in the WYSIWYG editor will cause your prior Markdown to change throughout the note. Even a small change in the WYSIWYG editor can cause this.

If you find you get undesirable results, it’s easy enough to revert the changes or go back to a prior version of the note. However, it may be inconvenient to use the WYSIWYG editor due to that concern. Perhaps avoid editing in the WYSIWYG editor unless necessary, and stick to editing in Markdown only. The second panel is useful for checking the result of Markdown changes and reading the rendered note, but it seems a little unreliable at the moment for editing.

This is not a big issue for me; I am happy to work with Markdown.

Note: There may be an HTML-to-Markup conversion tool in Joplin which could return the note to some semblance of the markup originally intended; I honestly have not gone looking for something like that. WordPress plugins can do that conversion pretty well, and there are probably plenty of automated tools on web pages for the conversion, so a workaround may be possible, but the issue remains.

Sidenote: Using Joplin on a Chromebook

As a Chromebook user, I have been pleased to find that Joplin will run in an AppImage in the Linux container which comes with the current ChromeOS system. This is a simple and functional way to get Joplin running well in ChromeOS.

While the app interface looks a little different from other ChromeOS apps, there is only one exception to normal functionality in ChromeOS that I have seen so far; it does not work with the default speech-to-text built into ChromeOS (an occasional annoyance for me); otherwise, it seems to operate as expected.

Even the Joplin web clipper recognises the Joplin Appimage correctly for saving notes straight from web pages. This should not be a surprise since the option in Joplin App for enabling web clipper sets up a local port on your device that the web clipper detects and connects to; 127.0.0.1:41184.

PS:
As a defence for my prior admission of being a Chromebook user, I generally only need a thin client to work from. Most of my work is directed to various services or remote command lines.

Philosophically I cannot justify spending thousands on a laptop when I can get my work done just as efficiently on a $400 Chromebook. I even have a spare.