Solving the right problem (2022)

In the previous article , we took a look at what happens when the project applies a very good engineering solution to the wrong problem. This blog was an example.

Here is a story of another project that focused on the right problems from the start.

Getting priorities straight

A few years ago I wrote a small journaling web app to help me work on multiple projects at Trustbit. The purpose was to let me track any piece of information with as few distractions as possible.

A lot of effort went into the user experience . I've been ruthlessly killing and rebuilding all features that somehow affected the writing flow. I tried to minimize the friction and make the writing process as rewarding as possible. A little "pat on the back" once in a while can do wonders.

Throughout the development, I deferred any performance optimizations or tech improvements until it really hurt (it happened only once). Whenever the project could be dumbed down, it would be. I killed these awesome features that were a technical and cognitive burden:

  • full-text search
  • note tagging
  • expandable topic views
  • topic name auto-completion within the editor (to make it a wiki).

Plus, I have replaced Ruby-on-rails with a boring Python Flask app, file-based storage and SQLite indexing.

What is the measurable outcome?

Metrics speak for themselves.

I've been using Py-journal for ~70 weeks. It has more than 1700 posts. That is 3 notes on average per day!

Granted, only a small fraction of these notes could be shared publicly, but there are quite a few interesting stories there.

In the hindsight, what were the most important decisions leading to this outcome?

First, it takes only a few steps to write down something that belongs to an existing topic. Everything that is not so relevant is either faded or removed. The writing flow looks like this:

  • Open the web app (it lives in a persistent Safari tab).
  • Type a few letters to find the matching topic via instant fuzzy search (or hit "add" to create a new one).

image-20220106174834553

  • Hit "Enter" to open the first match.

image-20220106172216689

  • Hit "A" to add a new note and start typing right away.

image-20220106174718411

  • Write down the text in a visual editor. Copy-paste or drag images to attach them to the note.
  • Save when finished.

image-20220106172346323

Second, it is the job of the application to make content discoverable and rewarding. As soon as the note is saved, the application will parse the HTML and pull any optional headers. These are added to the global table of contents associated with the topic.

It is so rewarding to add a new note and see the outline grow!

image-20220106172216689

This Topic view also helps to maintain a high-level perspective on the progress . Along the way, it subtly encourages to continue the work : "Look, you have been working on this thing for so many years, what about digging a little bit more, just to keep the momentum"?

Weekly review shows the work done within a specific week (also rewarding):

image-20220106172614354

All topic images are included in the pinboard view (more fun than useful, but encourages to add illustrations):

image-20220106172434551

Filtered export creates a nice PDF for all work that was done within a specific time period in some topics. This is how I send work notes to my colleagues twice a week.

Lessons learned

Core lessons that I've learned while working on that project (and writing this retrospective):

  • Good engineering solutions can be a liability when they solve the wrong problem.
  • Pick the metrics to optimize and focus on them.
  • Remove anything that doesn't improve the metrics, this will make room for helpful additions down the road.

Given these lessons, I plan to fix the problems with this blog as well. It should be easier and more rewarding for me to publish here.

As a first step, I moved the entire blog to a tiny cloud VM (Debian) with the Caddy server running in front. The website is still static, but the editing loop is faster. It is a small relief. It is just the first week of 2022, but I'm already finishing my 3rd blog post.

Next possible solutions to explore:

  • introduce comments;
  • speed up publishing pipeline;
  • add WYSIWYG editor with image copy-paste experience;
  • make URL slugs and filenames - optional;
  • drop GA and set up privacy-preserving analytics to track the numbers of visits in Grafana;
  • set up target metrics that I want to achieve: number of weekly visits, number of blog posts, reactions etc;
  • encourage friends and colleagues to write more frequently as well.

We'll see how this works out 😄

I can send you an email whenever there is a new article. No more than once per week, likely - less. Subscribe here.

You can also subscribe via RSS Feed.

My personal email: Rinat[@]Abdullin.com. Please feel free to reach out! :)