How this site works

Once again, like I tend to do every other year, I've gone and rebuilt my website and blog. It's something I tinker with every now and then to improve how I share my thoughts and ideas, or sometimes just to freshen up the look and feel. This time around, it's less about the design and more about updating how I write and share content online. The hope here is that this would be the last time I would update my website in a significant way. Ideally, this should last a really long time.

Improving how I write

Several months back, I started organizing my writing and taking notes using the zettelkasten (German: "slip box") method. Sociologist Johannes F.K. Schmidt once said the process makes “serendipity possible in a systemically and theoretically informed way.” That's exactly how it panned out for me. Instead of writing long essays on topics I wanted to explore, I wrote shorter, atomic entries around specific ideas and linked them together. This shift granted me the freedom to roam through concepts without being hemmed in. I used Obsidian, a networked note-taking app, to tie all my disconnected thoughts together. If I had written about a specific idea once, I reference it wherever I need it in my other notes. A chain of notes can represent and explain big ideas with ease, and in full.

Most notes I've taken have never been seen or used again. Except maybe in high-school, when most of what we did was note-down, memorize and regurgitate. Unfortunately, I don't hope to improve this statistic much either; what I mostly care to preserve is the process of writing in itself. It's too valuable of a tool for how I think and understand more in-depth topics.

I've found making the best of my writing process is less to do with the tools and more to do with reframing the way I think about writing and publishing. The tools just facilitate the ways I want to capture ideas. This also means each tool is limited by its own opinions. If I could find a way to make the process the best it could be, such that it afforded flexibility and focused on writing to learn and understand, I think it could drastically improve the return on investment of writing, independent of how widely it's read.

The dream would be to represent how I thought about an idea or topic, in a visual medium, in writing, at the lowest cost of linearly transforming thoughts into words.

Why publish online?

There are many great reasons to write online. Most of the common reasons are to do with building an audience and growing some sort of side-business. I have some of those aspirations, but for the moment I'm focused on startups. Writing is mainly just an output for learing, sharing and connecting with like-minded people. So, what're the main reasons to write besides these apparent reasons? I think it's just the showcase of something innately human.

1. The ego-driven need to share and be heard.
2. The positive outcome of the psychological effect of writing to share publicly. It forces you to have a broader perspective and understand things well.
3. Fulfilling an urge to teach, and find other like-minded people.

The goal of these pages is not to be a model of concision, maximizing entertainment value per word, or to preach to a choir by elegantly repeating a conclusion. Rather, I am attempting to explain things to my future self, who is intelligent and interested, but has forgotten.Gwern (gwern.net)

On writing well

When sharing a thought or idea in writing, we want it to be understood. English is one language; it's constructed using grammar and semantics, along with some cultural flavour and best practices (pragmatics) such that most English speaking people can understand what you're saying.

Sometimes you also want your writing to be pleasurable. There's a lot of skill that goes into stringing words into sentences, sentences into paragraphs, and paragraphs into stories and arguments. It's a form of art. A tool that can be used to keep a reader's attention and evoke feelings. On the other end of this spectrum might be research papers and documentation, things that leave little room for interpretation and are just trying to get some discrete information across to the reader.

In the blogosphere, you see both: good underlying knowledge that's well communicated, and unproductive content that's pleasurable to read. There's a time and place for every kind of writing, except some of the ones sprawled between these extremes: cheap content using good writing to elevate itself. Let's call them sh*t sandwiches. Unfortunately, it's a common practice primarily used by online marketers to game search engines like Google into ranking them higher to generate more leads for their business. It's something like saying, "here, I created a little value for you; now you're obligated to look at our products."

I rank posts based on the underlying knowledge and originality. It's personal and varies depending on the category. The underlying knowledge must be valuable, something I want, and is communicated reasonably well. If it's something like a tutorial, I'll likely be able to find many sources that explain the same concept in different ways - I have choices and preferences.

There's a category of content that I consume where the material isn't the first pull. This is usually the people and companies I admire. They hold values and principles I resonate with and respect, which makes me want to learn more about them, what they do and how they do things. For this category of content, most of what I'm looking for is genuine, no bull-shit writing. I generally don't care if the writing is flawed or dry, it's a bonus that you don't necessarily need to lead with. I respect the person or entity enough to pay attention to them. I don't generally get options in this category, but that's also part of the point.

I grew up in a traditional Sri Lankan household that primarily spoke Sinhalese. My sister and I were taught English at a young age, but we rarely spoke English at home. My parents found it very important to make sure we spoke English well, but the experience felt unnatural for a long time. It's mostly to do with having to learn and practice a second language. All of the "normal" ways of speaking and writing, the pragmatics, were taught to us in a very sanitized manner. I guess what I'm trying to say is; we didn't get enough practice, and we didn't get to experience the vernacular firsthand. We studied English, but we rarely used it to communicate real things growing up. Generally, in English class, I made up the things I wanted to say because I needed to say something. Whenever I needed to explain something, I'd do it in Sinhalese, or if that weren't the case, I'd frequently use Sinhalese to fill in the gaps.

I'm fairly convinced this is true for anyone who goes through learning a language without being immersed in an environment that speaks it. Since moving west, I've picked up countless little things that've enriched the way I speak and make the way I talk sound almost as if I natively picked up the language. I don't know how much of this translates into writing, but I think the process is less obvious and requires a lot more work.

What people really care about when they read something is that they get some value from it. It answers an unanswered question, entertains, or discusses something that's of interest to them. It's a harmless selfish endeavour. One reads to both understand and feel understood. When I see blogs riddled with ADs and call-to-actions, I just see a vague form of manipulation. Maybe, in a lot of cases, it's transactional; writers trade their ideas and knowledge for a slice of your attention. At the very least, I hope to make this blog a fair trade.

Nothing lasts forever

... especially things on the internet. I wish this weren't the case, but, over the years, I've written many blog posts that I've abandoned across old websites, defunct publishing tools and ones I deleted because I no-longer align with the views within. I already know most of these online tools won't last a lifetime. The closest thing to pen and Moleskine when it comes to solving this problem for me would be markdown files that I can back up ten different ways, open across any number of useful writing tools, and programmatically parse when I want to publish or do something with the knowledge later.

Retiring the 'blog'

The problem with blogging is what it's evolved to mean today. It's become the fast-food equivalent of writing. Content that is mostly cheap, riddled with clickbait and rarely timeless. If that isn't enough, the format of a blog is to cover a precise topic or tell a story; with a beginning, middle and end, in around 2000 words, usually with some agenda.

There is a big difference between the final output and the raw inputs that go into learning and then writing about something new. The process of learning is fragmented. You don't just linearly learn about one topic; there are many side thoughts and threads you need to follow that lead away from your main subject that either point nowhere or eventually loop back to give you clarity and context. This is one of the reasons to love Wikipedia - every article links out to dozens of sources and additional material that is required to understand the topic at hand.

Unfortunately, after you're done with the learning process, you're expected to condense this down to a coherent narrative without confusing or overwhelming the reader. For the sake of clarity and time, this usually manifests into sharing only a thin slice of what you've learned. This makes complete sense when you have an agenda for your reader, or the goal is to educate folks on a specific topic without overwhelming them and getting too carried away. These are well-scoped pieces of content for a narrow slice of users who know what they want or already have the rest of the parts and are just using your content to fill in a blank in their jigsaw puzzle on that topic.

There's no expectation you need to read anything I write from top to bottom. My longer posts are just some thoughts and facts organized into a semi-coherent narrative with sensible headings, context and navigation, leveraging the visual presentation to make the experience the best I can make it be for the reader.

Success criteria

I am setting some expectations for what I want this website to facilitate.

1. I never want to write about the same thing twice.
2. I want to write as I think - many side thoughts and ideas. I want to capture a lot of those thoughts into a post without complicating the main thread.
3. I want to dive deep into topics and improve my writing over time. How do I set expectations for this?
4. I want to organize and present my ideas in a reasonable manner so that a reader can find it valuable.
5. I want to write in a timeless format on a computer. Things on the internet don't last forever; a markdown file can live in a memory stick or some other optical storage format forever (at least for all practical purposes.)
6. I want to be able to parse, search, organize and re-organize my writing in code. Each post breaks down into several sections with headings, sidenotes, links and footnotes.

How I built this site

Using Markdown

This is the timeless format that I already use. I can work on posts locally and offline, back them up with Git, and easily publish them online since most blogging tools support markdown anyways.

The stack

It's not that complicated, just very opinionated.

Tools

Posts, pages and documents are all represented in markdown files. I usually have all my articles and pages sitting in one folder. Each article or page gets its own folder that stores a markdown file and the images and files referenced within.

Website

This website is built on Gatsby. It took me about 2-4 hours of work to get it set up and move over my old content.

Static Hosting

Once the site is compiled into HTML, it's deployed to and hosted on AWS. I'm not going to do a deep dive into this because the entire point of doing something like this was to be opionated, so you should too. The Gatsby documentation contains a lot of details around achieveing this with most hosting providers.

The features

These features list below aren't all that extraordinary. It just employs some tools that are commonly used in printed books to make the content on a webpage more natural to navigate. This isn't all that this webpage can contain. The goal behind using Gatsby was to add any number of features like this, over pain old markdown files, with relative ease. These features are what I needed to make this post possible; if I wanted to have an interactive gallery or Jupyter notebook embed on my next post, all I need to do is spend a hours creating a react component that renders it.

Table of contents

Very important because you shouldn't be reading this entire post linearly from top to bottom. Start reading, skip things that don't interest you, jump around the document and take the time to understand whatever interests you. Use the table of contents and headings as your guide.

Sidenotes

Sidenotes for side thoughts. Follow along as I get sidetracked or explain the same thing in different words. Sidenotes stay close to where they're at least loosely relevant to the main thread. They are always titled for additional context.

Highlights

(Beta - only works in some browsers.)

You can highlight on this page. Try it. The website will remember your highlights the next time your visit. The feature uses local storage on your browser to remember your highlights. It should last for as long as you don't clear your browsing history.

Source code

I've shared the core source code that I used for this site on GitHub. (Coming soon...)

Conclusion

I started writing this about a week ago and I'm resonalbly happy with the progress. I explored a bunch of possibilities around how I could facilitate more flexible writing online. Having decided Gatsby was what I needed, it was fairly straightforward to get it setup for my needs. There's much work to be done improving both the technical and content aspects of this site.