A wizard reading in a library.

Notes on writing as a software engineer.

Last Tended-
Planted
StatusSeed
A kung fu master & student practicing.

Why Write?

Hone your craft

To hone 1's craft, you need to explore it in different ways. My craft is creativity on the web. I began exploring this area by making web pages. This involved learning design & programming. When I got to a level of competency with these skills, I needed to explore the area through more lenses. Writing is 1 of those lenses.

[Writing is thinking]. I believe in this concept so completely that I'll take the importance of writing a step further: I find it valuable to write even if only for my own benefit. Writing is a linear process that forces a tangle of loose connections in your brain through a narrow aperture exposing them to much greater scrutiny. In my experience, discussion expands the space of possibilities while writing reduces it to its most essential components.
- Andrew Bosworth (early Facebook employee)
Portrait of Jedi Master Yoda

Communication is a valuable skill that you can train

Communication is hard. A common misconception is "Of course I'm a good communicator, I've been doing it all my life". In my experience, a lot of problems result from this misconception. Part of the above statement is true, “I've been doing it all my life”. Whatever your goals, you will need to communicate. Depending on your skill level, these parts of your journey can slow or quicken your progress. The more you write, the better you become at writing, the better you become at communicating.

Document your journey

I live my life by following my passion. I use a digital garden to document that journey. I make it public, showing people what I discover. This builds credibility & an audience. Opening new paths that otherwise wouldn't happen if you traveled in private.

Even when I write for my own benefit, it is undoubtedly a bonus that at the end I have a document which I can easily share to invite critiques or enlist support. I know of no more scalable way to engage a large audience than the written word.
- Andrew Bosworth (early Facebook employee)
Portrait of Kung Fu master Pai Mei
A schematic of a space station that looks like a moon.

Structure

I like Chris Behan's approach to writing, using the single-responsibility principle:

  • An article should have 1 big idea.
  • Each paragraph should have 1 small idea that contributes to the big idea.
  • Each sentence should contribute to the small idea.

I approach content like poetry, every word comes at a cost. I draft sentences as dot points & ensure each has a clear purpose & communicates it.

Good writing is like good code, it's simple, efficient, & structured. You should strive to use the simplest words that get the point across. If something in your writing doesn't need to be said, don't say it. Your writing, like your code, should be structured in a way that maximizes understanding for the reader.
- Chris Behan
Portrait of Kung Fu master Pai Mei

I don't use an introduction or conclusion that summarizes what you are about to read & what you read. These techniques echo learning through repetition. Getting something to stick by repeating it. My experience as a teacher has shown me there are better ways. Cut down on the content & make what remains stick. People who saw the 1st Star Wars didn't need the plot points summarized at the start & end to remember what happened. It used the approach of story to reach its audience.

An elegant woman looking in the shopfront of a jewelery store.

Writing Style

I have read a lot of advice about finding your voice. Your unique writing style. Attempting to create your style while writing blurs your focus. When writing, I only focus on 1 thing, communicating the idea in the best possible way. Michelangelo didn't attempt to paint like Michelangelo. He attempted to paint good. By doing that, over time, his style emerged.

Don't try to be original. Just try to be good.
- Paul Rand

Steal

Good artists copy, great artists steal.
- Pablo Picasso

I do use techniques from other writers that are effective at communicating. When reading, if I come across an effective technique an author has used, I screenshot & keep it in a scrap book. For example, how Scott Galoway introduces content about the potential of Apple's assets. He uses a metaphor (with image) of a gun loaded with bullets marked with icons.

A revolver barrel with bullets marked with product icons.
A performer standing on stage in front of an audience at the Opera.

Audience

When writing, I only focus on 1 thing, communicating the idea in the best possible way. I don't have a specific audience in mind. If I did, I would begin to manipulate the content to serve them, blurring my focus. When I write, I write for myself, to reflect.

Warren Buffett addresses the early drafts of his shareholder letters to his sister, Dorothy. Once he finishes it, he replaces her name with 'Shareholders'. The lesson: Writing for a huge audience is a fast track to getting writer's block, so write for one person instead.
- David Perell
Portrait of wizard Gandalf the Gray
A golden statue.

Content

For me, writing is about exploring an area of interest. Creating content begins by consuming it. I have a list of Google Docs, named by topic. For example, WebAssembly, design-color, design-typography. Whenever I'm exploring & come across a piece of content of interest, I screenshot & add it to 1 of these files.

When I sit down to write, I add notes to these snippets such as:

  • summarizing the ideas it's communicating,
  • add questions the snippet raised,
  • identify links to other snippets &
  • pull out quotes that effectively communicate an idea.

This forms the basis of an article.

An athlete with their fist in the air.

Schedule

When people ask me for advice on blogging, I always respond with yet another form of the same advice: pick a schedule you can live with, & stick to it. Until you do that, none of the other advice I could give you will matter. I don't care if you suck at writing. I don't care if nobody reads your blog. I don't care if you have nothing interesting to say. If you can demonstrate a willingness to write, & a desire to keep continually improving your writing, you will eventually be successful.
- Jeff Atwood - Stack Overflow co-founder
Portrait of Jedi Master Yoda
2 scientists attempting to communicate with 2 aliens using symbols.

The End Goal

The purpose of writing is communication. If you’re trying to communicate, I don’t think it’s effective to restrict yourself to only 1 approach. An idea may be 70% communicated through text. Tweaking the text to reach 71% may be like getting blood from a stone. However, adding an image may get you 95% there.

My experience as a teacher lead me to the idea the communication approach must match the content. An idea echoed by Jonathon Blow. Imagine trying to communicate the math idea you can add numerators if they have the same denominators. Back in the time of Euclid, this is how it was communicated:

Since then, mathematical notation was invented, allowing us to communicate the same idea in a more effective way:

The browser allows for a range of communication approaches:

  • text
  • image
  • video
  • interactive widgets
  • comic
  • design
  • ...

Allow the content to dictate which approaches to use. This is why I created my own digital garden rather than using a service like dev.to. Although I would get more reach, the approaches at my disposal would be restricted. My focus is not to maximize reach but to communicate ideas in the best possible way.

A space ship's docking bay with various equipment.

Tools

  • Hemingway App - makes sure that your reader will focus on your message, not your prose.
  • Grammarly - catch spelling & grammar issues.