Braintapper Logo

Recent Blog Posts

My SARS-CoV-2/COVID-10 Links article is up

March 20, 2020 by Steven Ng

The mass spread of the SARS-CoV-2 virus in March 2020 effectively changed the world. We are seeing reactions at both extremes - panic and dismissal. Personally, I think a huge part of this is related to communication. The traditional news and media organizations have done a satisfactory job of reporting events, but not as good a job at educating people on just about everything.

Fortunately, many individuals have stepped up and provided better informative sources than the ones you'll get by watching the news or reading newspapers.

I have posted an article with links that I consider to be of high quality as it relates to the pandemic.

As I find new quality content, I'll add it to that article.

Let's be safe everyone, we will get through this.

Minor Site Update

March 18, 2020 by Steven Ng

Just a minor update to the site. As part of my "continuous improvement" process, I've made the site more mobile friendly. It's not that the first iteration wasn't viewable on a phone, but the top navigation reflows to different screen sizes more cleanly than in the past.

There are some minor UI changes, as the Search box has been reskinned.

I've integrated my "standard" Svelte stylesheet into the site. Gotta eat your own dogfood, as they say.

My Curated List of Free Fonts is Up

March 12, 2020 by Steven Ng

An important part of any web developer/report designers tool chest is a good set of fonts.

I've posted a new article entitled My Favorite Free Fonts in the Articles section of my site.

Not everyone (myself included) can afford to license a typeface like Avenir Next, Proxima Nova or Gotham, so I've compiled a set of go-to fonts that I use in my projects.

The article is organized by download site and then categorized by type.

Of the list, my favorite fonts are:

I'll be updating that article periodically, as I discover new favorites, or if my tastes change.

It's 2020 and I'm Still Using Coffeescript

March 10, 2020 by Steven Ng

Get Off My Lawn

I find that technical choices can be an especially polarizing topic among techies, especially with the newer generation.

While tech has never been immune from the "smartest guy in the room" syndrome, programming language debates can often be fatiguing to watch, and soul sucking to engage in.

So here's my old geezer "you don't know how good you have it" lecture. When I was coming up in the tech industry three decades ago, there were only a handful of programming languages you could get gainful employment in. It was usually a some variant of C, a mainframe language, Java, or for a time Visual Basic. Everything else was dismissed by the smartest guys in the room as a "toy language".

Today, you can get gainful employment in a wide variety of languages. In addition to the old standbys, Python, Ruby, Javascript, Typescript, Erlang, Go, Swift and a pile of other languages are pervasive and popular. I think it's great that there are so many acceptable language options today.

If you've been watching the Javascript world, you'll probably notice that everyone in the know has jumped onto the Typescript bandwagon over the past few years.

I don't have any quibbles with Typescript, but I haven't jumped on that bandwagon... yet. I'm still using Coffeescript. If you're not familiar with Coffeescript, it's a language written in Javascript that compiles into Javascript. Wait, what?

Coffeescript

This description will date me, but Coffeescript is essentially Javascript shorthand. It lets you to write Javascript with a Ruby-ish/Python-ish syntax. Coffeescript is sweetened by a pack of syntactic sugar resulting from the elimination of semicolons and braces as well as the improved readability of nested logic using indented whitespace.

For example, this Coffeescript snippet:

palette =
  "gray" : ["#dee2e6","#ced4da","#adb5bd","#868e96","#495057","#343a40","#212529"]
  "purple" : ["#e5dbff","#d0bfff","#b197fc","#9775fa","#845ef7","#7048e8","#5f3dc4"]
  "blue" : ["#dbe4ff","#bac8ff","#91a7ff","#5c7cfa","#4c6ef5","#3b5bdb","#364fc7"]
  "green" : ["#c3fae8","#63e6be","#20c997","#12b886","#0ca678","#099268","#087f5b"]
  "yellow" : ["#fff3bf","#ffec99","#ffe066","#ffd43b","#fcc419","#fab005","#f59f00"]
  "orange" : ["#ffe8cc","#ffc078","#ffa94d","#fd7e14","#f76707","#e8590c","#d9480f"]
  "red" : ["#ffe3e3","#ffa8a8","#ff8787","#fa5252","#f03e3e","#e03131","#c92a2a"]

colors = Object.keys(palette)

shades = ["lightest","lighter","light", "", "dark", "darker", "darkest"]

foreground = (shade,background)->
  color = "#ffffff"
  switch shade
    when "lightest","lighter","light"
      color = "#495057"
    when ""
      if background == "yellow" then color = "#495057"
    when "dark"
      if background == "yellow" then color = "#495057"
  color

Compiles to this:

var colors, foreground, palette, shades;

palette = {
  "gray": ["#dee2e6", "#ced4da", "#adb5bd", "#868e96", "#495057", "#343a40", "#212529"],
  "purple": ["#e5dbff", "#d0bfff", "#b197fc", "#9775fa", "#845ef7", "#7048e8", "#5f3dc4"],
  "blue": ["#dbe4ff", "#bac8ff", "#91a7ff", "#5c7cfa", "#4c6ef5", "#3b5bdb", "#364fc7"],
  "green": ["#c3fae8", "#63e6be", "#20c997", "#12b886", "#0ca678", "#099268", "#087f5b"],
  "yellow": ["#fff3bf", "#ffec99", "#ffe066", "#ffd43b", "#fcc419", "#fab005", "#f59f00"],
  "orange": ["#ffe8cc", "#ffc078", "#ffa94d", "#fd7e14", "#f76707", "#e8590c", "#d9480f"],
  "red": ["#ffe3e3", "#ffa8a8", "#ff8787", "#fa5252", "#f03e3e", "#e03131", "#c92a2a"]
};

colors = Object.keys(palette);

shades = ["lightest", "lighter", "light", "", "dark", "darker", "darkest"];

foreground = function(shade, background) {
  var color;
  color = "#ffffff";
  switch (shade) {
    case "lightest":
    case "lighter":
    case "light":
      color = "#495057";
      break;
    case "":
      if (background === "yellow") {
        color = "#495057";
      }
      break;
    case "dark":
      if (background === "yellow") {
        color = "#495057";
      }
  }
  return color;
};

You'll notice that the Coffeescript code is terser, which in my opinion, makes it more readable.

Coffeescript, however, does not absolve you of needing to know any Javascript, as debugging still requires full Javascript fluency. As I mentioned, Coffeescript is shorthand for Javascript, but not a replacement.

Why?

So why do I still use Coffeescript, even though it's 2020 and there are arguably better (and inarguably more popular) options?

Well, I started using Coffeescript when I started to do Ruby on Rails development roughly 10 years ago. If you've spent any time doing RoR, you'll know that indented syntax languages like SASS and Haml are incredibly popular in that world. SASS and Haml let you write CSS and HTML without becoming muddled with braces, semicolons or open and close tags. With Rails 3.1, Coffeescript adoption became even more widespread among RoR devs.

Using Coffeescript with Rails has real benefits, as Coffeescript code has a lot of similarities to Ruby, which means less mental "mode switching" when jumping back and forth between front-end and back-end code, which makes it feel like you're writing in the same language across the breadth of your entire application.

So back to the question of "why", I still use Coffeescript today because it allows me to translates my thoughts into code faster without worrying about details like braces and semicolons. The use of whitespace also makes the code incredibly easy to read for me, which makes debugging much faster. The primary cost of this language is that it needs to be compiled (which for me happens in near real time, since I use a Gulp script to compile my code when files change. Now that I'm working with Svelte, which is a compiled web development platform, the notion of Coffeescript's compilation step as an inconvenience is moot, as Svelte requires compilation anyways. I simply include Coffeescript as a seamless preprocessing step in my Svelte workflow.

Looking Forward

I have been tempted to switch to Javascript (or even Typescript) now that I've been using Svelte, mainly because of some Coffeescript-unfriendly idiosyncracies in Svelte (i.e., export let, let and $: { someCode}). Those idiosyncracies, however, are easily solved with the use of backticks, which in Coffescript, lets you pass through raw Javascript in your Coffeescript code.

So while my use of Coffeescript might be considered passé to some, I still find it to be a valuable part of my toolchain, because I am more efficient and productive with it. Having said that, I'm not at all ignorant or resistant to change. Myself, I'm partial to tools that work the way I think, and sometimes timing matters. Industry-wide preferences often become replaced with even newer ones.

For example, I've been looking to move away from AngularJS for newer web projects for some time. I considered Angular (AngularJS's successor whose name is not at all confusing, smirk), React and Vue. I was about to jump on the Vue bandwagon until I heard about the Svelte 3 announcement, and was simply blown away by how it ticked all the boxes that I was looking for in an AngularJS replacement. Had I made my choice earlier, I'd be a Vue developer right now. Timing affects outcomes.

So yes, I could adopt Typescript now, but I need some convincing that at some point Typescript won't fall out of favor of something newer, faster and better. In the end, whether you're using Coffeescript or Typescript, you're still compiling that language to plain old Javascript, since that's what runs on browsers and NodeJS. So why not stick to the tool that works best for you, whatever that may be?

Clips vs. Notes

February 4, 2020 by Steven Ng

All-in-one software tools can be very useful, as they can consolidate multiple functions while minimizing window proliferation, etc.

For example, I recently got introduced to a nifty (albeit unfortunately named) little tool called Snowflake, which lets me have terminal windows and an SFTP file browser contained within a single window. While imperfect, I find it works better for me than using WinSCP.

Snowflake, however, is a utility. All-in-one applications in other contexts may not offer the same benefits. If you haven't already gathered it from the title, I am no longer a fan of using an all-in-one system for notes and web clips.

Capturing data is a little different than a utility in that you're accumulating data into an ever-growing bucket. And if your tool is collecting different types of data, that bucket is going to get harder and harder to navigate over time.

Yes, you can categorize and classify, but that is work. And by work, I mean time and mental effort. It then begs the question of how much time do you want to spend managing that ever-growing, ultimately unsustainable bucket of data.

I used to use Evernote for self-created notes and clippings. I thought it was great, especially the web clipper, but after years of accumulating thousands of items, I realized that all-in-one data collection was a romantic notion more than it was a practical one. In other words, I was in love with the idea, but not the execution.

This realization didn't really materialize until I spent time hunting for alternatives to Evernote. It wasn't so much that there are not good alternatives to Evernote. There are plenty of good alternatives to Evernote, such as OneNote and Joplin.

The problem is that Evernote and its ilk are simply not a good model of data collection for me. I found that mixing in my notes with clipped content in the same tool just created a mountain of data that got hard to sift through. And with that realization, I decided to separate out my note taking and web clipping requirements into two discrete applications.

For notes these days, I basically just use a folder in Dropbox that contains a combination of markdown and Dropbox Paper documents.

For clipping, I use Wallabag, which is similar to Instapaper.

I have found this segregation of data to be very useful in terms of my daily workflow. That Wallabag will scrape URLs (it is mostly successful in its attempts) is also handy in that I don't have to worry about broken links in the distant future.

By eliminating clips from my notes, it's now much easier to find what I'm looking for, and it's been working very well for me.

Of course, I need to add the obligatory "your mileage may vary" disclaimer, but if you're finding yourself struggling with information overload because you're using an all-in-one data collection tool, maybe the best fix is to break up your solution into multiple tools.

Apps > Install this site as an app

January 29, 2020 by Steven Ng

Confessions of a Tab Hoarder

I've been using Edge Chromium as my primary browser on Windows for quite some time now, and I like it a lot. In the past few months, I don't think I've opened up Chrome on Windows except by mistake. Honestly, I don't miss Chrome at all.

I've always had a bad habit of having too many tabs open (often more than 50). More often than not, instead of trying to find an existing tab, I'll just open a duplicate, which exacerbates my problem.

Roll Your Own PWA

Edge has a very cool feature that lets you roll your own PWA (progressive web application) out of a web site. In other words, it will create a single-site application that is accessible from the Windows Start menu. It also means that the generated PWA gets its own spot on your taskbar, using the site's favicon as the icon. No more tab hunting.

For a tab hoarder like me, this is a life changing feature. I have a ton of web apps that I'm constantly using throughout the day, so this makes life a lot easier.

As always, there's a catch. The feature doesn't work great with all sites/web apps. If the web app you're using has to proliferate new tabs or windows, it's not a great candidate, as those tabs/windows will open up in Edge. For example, if you're thinking this technique is a great way to use Dropbox Paper or Google Apps1, you're wrong.

On the other hand, if you're using it for something like Feedly, Github or PGAdmin4, it's great. I have a lot of containerized web apps like PiHole that work great as PWAs.

So how do you enable this magical feature?

If you're running Edge for Chromium, just browse to a site (ideally, you go to the exact page you want to start from, since that will be the page you see when launching the PWA), go to the menu, Apps > Install this site as an app. Give the app a new name if the default isn't to your liking, and bam, you're done!

Footnotes

  1. If you're looking for a way to handle multiple Google accounts for email and calendaring, check out Easymail for Gmail. I bought a license during the 1.x days, and it was fine but not something I could use daily. The latest release, 2.x, is a complete rewrite, and works much better than the previous iteration. Full disclosure, I wasn't paid to say that.

Dropbox Paper Is Surprisingly Good

January 23, 2020 by Steven Ng

Note Taking Hell

It's no secret that I've been hunting for the "perfect" note taking application for years now.

I dropped Evernote a few years ago as a multi-purpose tool, and have been trying to find a replacement ever since.

Note taking is a very personal in that you develop some very specific tool and/or process preferences that you don't really want to compromise on. What works for one person may not work for another.

My Own Criteria

For me, my core requirements, in no particular order (they are numbered for reference), are/were:

  1. A Windows native desktop client
  2. The ability to have my notes in a hierarchical file structure that was available in a tree view (more important on the desktop than mobile)
  3. Cloud sync or storage
  4. Live conversion from Markdown to formatted text without having a preview pane
  5. Ability to access and read my notes from my Android phone. Editing and creating is only a nice to have, since I'm pretty much useless with a touchscreen keyboard.
  6. The occasional ability to collaborate on notes/docs with others (this one's not a deal breaker)

Criteria that I thought were important but ended up being unimportant:

  • Web clipping
  • Pen support

I always found that web clipping polluted my notes a little, and I recently switched to using Wallabag for all my bookmarks and web clippings. Wallabag is very similar to Pocket, and it's been working well for me so far.

For years, I've had this crazy notion that I wanted an electronic version of the paper notebook that I bring to meetings. The problem is that the available solutions work better in my imagination than they do in real life. I've pretty much given up on the idea of a stylus-based tool, and no longer consider it meaningful criteria in determining what type of note taking tool(s) I use.

Options I Considered

With my criteria considered, some picks I tried and considered were:

The one option that did look good to me was Bear.app, but it's really only for people in the Apple ecosystem, which I'm no longer a part of.

Even if they do eventually support Windows and Android, I don't know that I'd switch to Bear, given my experience with applications that are Apple-centric. For example, I've always felt like the Windows and Android clients for 1Password were second-class citizens in terms of the product line.

A folder full of Markdown files

One of the first things I tried was a Dropbox folder full of notes using a text editor like Sublime Text. This method wasn't horrible, but the problem is that I have multiple text editors open at any given time, and it got hard finding the right window. Having said that, the solution I'm using now has the same problem, except within a web browser.

Requirements satisfied: 1, 2, 3, 5

OneNote

I have a love/hate relationship with OneNote. On one hand, it's very powerful, on the other hand, it has so many user interface quirks that drive me bonkers. It's also not really a Markdown centric tool, even though it has a few Markdown-like shortcuts, like using asterisks to start bullet lists.

Requirements satisfied: 1, 2, 3, 4 (limited), 5, 6

Google Docs

Google Docs is fine, but the experience feels more like using a traditional word processor than a note taking tool. Also, it's not Markdown centric.

Requirements satisfied: 2, 3, 4 (limited), 5, 6

Joplin

Joplin is a Markdown centric alternative to Evernote. It lets you sync your notes using Dropbox. It's pretty good, and has a web clipper that works quite well. I think the main weakness of Joplin is that it it doesn’t do live Markdown conversion the way I’d like it to.

Requirements satisfied: 1, 2, 3, 5

WikiJS

WikiJS is a self-hosted wiki. It has a lot of potential, but as of the time of writing, it's not quite there yet for me to want to use it daily. To be able to use it outside of my LAN, however, I'd have to open up a firewall port, or host it on a server somewhere, which is something I’m not interested in doing.

Requirements satisfied: 2, 3, 5, 6

Bookstack

Bookstack must be the most recommended note taking tool on /r/selfhosted. I gave it a shot, bailed, and then gave it a shot again. For note taking, it had way too many quirks with respect to the user interface that just annoyed the hell out of me. If, however, I was authoring a book, it would probably be my first choice for that task.

Requirements satisfied: 2, 3, 5, 6

Dokuwiki

Dokuwiki is a simple file based Wiki. It's ok, but I struggled with the idea of using it every day. It just wasn't very enjoyable to use.

Requirements satisfied: 2, 3, 5, 6

MarkText

MarkText is similar to Bear, but lacking much of Bear's polish. It has a lot of potential, but it's still too buggy and quirky at the time of writing.

Requirements satisfied: 1, 2, 3, 4, 5

No Clear Winners

So there is obviously no tool that checks all of my 6 main requirements completely. Short of writing my own tool (which I considered, but decided I had other projects more worthy of my time), I had to give up on 100% coverage of my requirements. The solution I ultimately choose would obviously require me to compromise on what I want.

Revisiting Paper

I tried Paper way back when Dropbox announced it, but honestly, it left no lasting impression on me.

I gave it another cursory shot a few weeks ago (after upgrading to a paid Dropbox subscription), and discovered that its live Markdown conversion is excellent. It is definitely better than MarkText in this regard.

It wasn't until I had to collaborate on a server installation document that I was truly sold on Paper. Before I get into the nuts and bolts of Paper, the requirements it satisfies are 2, 3, 4, 5, 6. Right now, there's no desktop client that's been released to the public. I'm hoping they release something, even if it's just an Electron app. I need something that occupies its own button on my taskbar instead of having to cycle through my browser windows to find my Notes. Having said that, in daily use, I am finding that Paper is a fantastic note taking tool.

Markdown Support

The live conversion of Markdown works very well in Paper. The reason why Markdown support is so important to me is that it saves me a lot of time. When I'm writing documentation, the ability to style documents using markup alone is incredibly powerful. There is no mousing around for styling or setting heading levels. I find pumping out documentation to be a noticeably faster and smoother experience.

So not only do I now use Paper for notes, I also use it for work-related documents.

Where I can, I'm actually writing documentation in Paper and exporting to Word or PDF. I can say without any reservations that the editing experience in Paper is the main driver for it being my daily writing tool, in spite of any glaring weaknesses it may have.

Other Useful Features and Details

The checklist feature in Dropbox is pretty darned cool. You can assign dates and people to checklist items, and get notifications too. Paper can also aggregate the checklists on all your Paper documents into a single view.

The implementation of this feature has me rethinking how I approach project management tools in general. I still have to do some practical experiments with Paper in this regard, but I have a feeling that it can do what I need, which is saying a lot.

There's a Timeline feature that lets you insert a horizontal timeline, which can be used to create a pseudo Gantt view. This could be a great feature for collaborating on larger projects.

Like Word and Google Docs, Paper has popular features like commenting, version history, and live collaboration.

It may sound corny, but the default stylesheet for the document is really nice. Not Bear nice, but a close second. I absolutely hate the default stylesheets in Word, Onenote and most other tools. When writing long documents, you get a hiearchy map on the right side of the Paper document to allow you to jump quickly to headings in your document.

You can export your document to Word for finalization, or if you don't need to make any edits, you can export your document to PDF.

There's a presentation mode for your document, but I haven't found a good use for that feature.

Deficiencies

While I am really liking Paper a lot, the user experience isn't all sunshine and rainbows. If the editing experience were not so good, I would consider some of these deficiencies to be deal breakers:

  • The Android app experience is horrible. You can't dig for a file based on location. It's basically an "all" or "favorites" view. This is fixable, but I have to admit, it is very annoying.
  • No desktop application. At any given moment, I have way too many browser windows open, each having too many tabs. Finding the window containing a Paper document is an exercise in patience. If I could at least have a dedicated Paper button in my task bar, that would save me a lot of stress.
  • Paper documents are server-side documents. They are not real documents like Word or text documents. In your local Dropbox folders, the files are basically links to the Paper web app. If you have any hangups about having readable local copies, you're going to absolutely hate this about Paper. If your Internet goes out or the Paper service goes down, you are f-ed. I think a Desktop app that can have local copies would mitigate any concerns related to this.
  • No easy conversion feature for existing Markdown documents. I couldn't find any way to convert my existing Markdown notes to paper short of opening the file, pasting it a new Paper document and deleting the Markdown file.

Verdict

As I mentioned earlier, whether Paper is ideal for you depends on your own preferences. When it came out in 2015, I thought very little to nothing about it. I was relatively unimpressed.

Years later, after giving it a new attempt, I find the application to be a revelation. It has improved so much that it has quickly become my writing tool of choice. In fact, the draft of this blog was written in Paper and pasted into my static site generator.

Paper may not be for you, but if you care about using Markdown for writing, you should definitely give it another shot. You might be pleasantly surprised at how good it is.

Basecamp's Guide To Internal Communication

January 10, 2020 by Steven Ng

Basecamp published their guide to internal communication recently, and it is insightful and excellent.

Some highlights:

Meetings are the last resort, not the first option.

...

If your words can be perceived in different ways, they'll be understood in the way which does the most harm.

...

"Now" is often the wrong time to say what just popped into your head. It's better to let it filter it through the sieve of time. What's left is the part worth saying.

...

Write at the right time. Sharing something at 5pm may keep someone at work longer. You may have some spare time on a Sunday afternoon to write something, but putting it out there on Sunday may pull people back into work on the weekends. Early Monday morning communication may be buried by other things. There may not be a perfect time, but there's certainly a wrong time. Keep that in mind when you hit send.

I highly recommend that you give the article a read.

Check out my Articles

January 6, 2020 by Steven Ng

As mentioned in my first post, I have an Articles section on the site where I'll be posting evergreen articles that will continue to be updated over time.

I have two articles in place now:

  1. The Windows Software I use to Stay Productive - This is a list of software that I recommend for Windows users.
  2. My Favorite Self-Hosted Applications - This is a list of mostly Docker containers (for now) that I recommend running in your own environment.

I have a queue of other useful articles on their way, and will announce their creation or updates here on the blog.

Convert an Outlook PST to JSON

January 6, 2020 by Steven Ng

I had to archive an Outlook mailbox to a PST file recently, but I'm not a huge fan of using Outlook for finding e-mails.

I looked around for tools that would convert a PST to JSON so I could load my data into something like Postgresql, but I didn't find anything that was free (I only need to do the conversion once).

I ended up searching for an NPM that could extract objects from a PST, and found epfromer's pst-extractor..

Using that NPM, I made a simple command line tool for Windows that can extract a PST into a JSON file.

Since my requirements were modest (one time use, reasonably sized PST file), I didn't really design it to scale. It doesn't support password protected PSTs, and I can't guarantee that it will run on a giant PST file if your machine doesn't have enough memory, but it's there if you need the functionality.

To use it, just download the executable from Github.

The command structure is pretty straightforward. From the directory of the executable, use:

pst_to_json -s /path/to/file.pst -d /path/to/output.json

There are some additional switches, but the above command is all you need to accomplish the task.