I’ve written over 220,000 words on my blog since 2014, when I first started writing online. This year, I finally feel like I can write well, in a way that’s useful for you, the people reading what I write, and myself, who wants to communicate something to the rest of the world.
In the intervening half-decade, my writing workflow has changed dramatically as I’ve become more efficient and expressive in my writing. This is a story of how a blog post like this one gets made.
- Collecting sparks
- Calibrating expression
- Outline: the shape of an idea
- Revise, revise, revise
- Publish
- Epilogue
Collecting sparks
Most of my blog posts start from a spark of an idea that I discover in conversations or reading. Sometimes, it’s as straightforward as a question I get so often that I want to put down an answer in writing. But usually, these “sparks” are things like:
- An analogy I think is interesting
- An underappreciated trend in the world / industry
- A technical topic I want to deep-dive
- A new approach / perspective to an established problem
The first time I get an idea like this, whether in the shower or at a coffee shop talking to a friend, I just write it down on my phone, in the moment. The point here is not to have a fleshed-out idea or to spend a lot of time thinking about it, but to keep it in my mental periphery so that the idea has the time and space to grow and snowball into something more interesting and meaty. I’ll commonly have 3-5 “seeds” of blog posts like this at any moment, that I come back to on a regular basis.
Calibrating expression
Once the idea is in my mental space, I’ll add related ideas and approaches to it over time, until there’s enough substance to the idea on which to build a post. When I read articles online relating to the topic, I’ll throw those links into my notes. At this point, I’m just collecting raw material that I might need later, to mold into something more structured.
The most useful thing I’ve started doing at this stage is to bring it up in conversation with smart people, and try to explain the idea and get their feedback or disagreements. Besides the obvious benefit of feedback on the idea, I also get better at choosing the right words and phrases to describe it, so when it comes time to write it down more permanently, I know the right way to put the idea onto paper that’ll resonate with you, who’s reading what I write.
Sometimes, I’ll only stay in this sort of “collecting ideas” phase for only a day or two. Other times, with more high level ideas or arguments drawing from experience, I’ll let it simmer for months until I’m confident that I’ve found the right way to articulate it in a way that resonates with people I’ve talked to.
I think this phase of calibration and polish, even before I’ve started writing, is the number one thing that’s made me a better writer over the last couple of years. Writing isn’t just the transformation of thoughts into sentences; it serves the purpose of communication. Good ideas, communicated ineffectively, isn’t good writing. My best writing is on ideas I’ve spoken about dozens of times, precisely because I’ve practiced and calibrated myself to the best way to communicate that particular idea. The phrases, word choice, order of arguments, what I mention first, what I leave until the end, what I omit completely – these are all things that I can experiment with, to calibrate the expression of my idea into someone else’s mind to match the version of it in my mind as closely as possible.
Outline: the shape of idea
Writing is a nonlinear process. I don’t start writing at the beginning, and I don’t finish writing at the end.
Instead, the way I write is a parallel, layered process. I take the initial pool of raw materials I’ve collected, and the particular turns of phrases I’ve settled on, and mold and filter them into iteratively more structured shapes until it reaches the form of a rough draft.
The first of these shapes is a rough outline. This isn’t a bulleted list of sentences or anything structured like that. I find those kinds of outlines harmful for my process because it feels like forcing myself to write a rough draft from the get-go. Instead, an outline at this stage is just a list of ideas and topics in the order I want to talk about them.
For example, the “outline” for this post was pretty short, because I was only sitting on this idea for a couple of days. It looked like this:
// writing flow: idea outline with comments and headers, expansion into rough draft, content revision, structure and wording revision, grammatical/spelling revision
// Inspirations
// writer’s block.
// writing tech – iPad
(The // at the beginning is a subtle reminder to myself that these words don’t belong in the draft – they’re just to help me think.)
These are the things I wanted to talk about when I started writing this post. From here, I try to get a feel for the shape of my idea.
Some ideas are just a flat, sequential list of things, like my piece on Lua. Some are studying an existing idea, and applying it to a new subject, like technical sympathy. Some look like inverted pyramids, with a single, core idea at the base, extended into a few different case studies and examples in the real world. Unbundling cloud is one such example.
This part feels as if I’m handed a mystery object in the dark, and I’m trying to study what it looks like with my touch, so I can relay it to a friend the next room over, also in the dark, ready to mold a bunch of clay into the same shape from my words. I can’t dive immediately into the details – the clearer the overall, macro-scale structure of my idea in my head, the better I’ll be able to copy it into the minds of whoever reads my words.
This kind of a top-down approach to writing also helps me decide early on who I’m writing for. The more specific I can be here about the reader, the more precisely I can mold my shape of the idea to cater to them.
Sometimes, before I write my rough draft, I’ll convert the rough, sloppy outline into a list of headings that I’ll use to structure my drafting. This second stage looked like this for this post:
The flow
// writing flow: idea outline with comments and headings, expansion into rough draft, content revision, structure and wording revision, grammatical/spelling revision
// inspirations, writer’s block, etc.
The tools
// tech, software used
But this changed quickly. I realized after starting to write that this flow-versus-tech separation wasn’t the right shape for my idea. Instead, my writing process is a sequential list of things, where each step involves a bit of tooling and a bit of workflow. This got me to the structure that I’ve kept through the final draft.
The rest is pretty straightforward drafting. I’ll just sit down and crank it out. At this point, if I’ve done my job right, it feels less like writing from scratch and more like filling in the blanks and expanding on existing ideas, because I’ve already figured out which topics I want to talk about, in what order, in what specific way, and I’ve marked it on my doc with headings.
I try to minimize revising during this process. Bad sentences can be removed later. My priority here is to put down ideas in the right order, and connect them in the right way.
For a rough draft and the following revisions, I’ve been using iA Writer lately on my iPad. It’s simple and distraction-free, and the iPad with a keyboard case allows me to write basically anywhere. The only extraneous UI element I see on screen while writing is a word count, which helps me keep my verbosity in check.
Revise, revise, revise
I revise my rough draft a few times to get to a publishable, final one.
The first pass is usually for high-level structure and shape. I scan the doc from top to bottom to make sure, after I’ve fleshed out everything, that the order I outlined before still makes sense, and there aren’t any gaps in my argument. This is where I’ll try to find any errors in thinking, any ideas I left out, or any distractions I added that I can probably do without. Sometimes, this leads to me adding an entire new section to the draft, or taking out several paragraphs I don’t think is necessary.
The second pass is for sentence structure and paragraph breaks. I’ll read through the draft, keeping an eye out for any sentences or paragraphs that are too long, or any awkward phrases that I can improve. The question I’m asking myself here is: “If someone else reads what I wrote, how do I make it as low-effort as possible for them to grok what I mean?” If there’s a simpler phrasing or sentence structure I can use, I fix those up.
The last pass is for spelling, grammar, and other typographical mistakes. For this step, I’ll usually move my draft over to my website’s codebase and generate a live preview version of the post that I can read aloud to myself, within the website. This allows me to ensure the post looks okay in addition to my last proofread. Reading the post aloud, it’s easier to catch small mistakes, and also ensures that I haven’t missed any strange sentence structures or run-on sentences from the last pass of revisions.
My goal here isn’t to be perfect – writing is never done. Instead, I try to get to a point where I can expect within reason that people reading what I wrote will easily understand what I mean, without room for misunderstanding. Beyond that, revising feels inefficient. Besides, if I later realize I was wrong, the beauty of the Internet is that I can always update the post later.
If the post warrants it, I’ll also solicit some feedback from friends at this point. Lately, I’ve also been adding illustrations to some of my posts. If I decide to, I’ll also draw the illustration at this time.
Publish
Since I rewrote my website in late 2019, publishing to my website is pretty simple. I use a static site generator called Hugo, with a fully custom theme that’s pretty minimal. Hugo takes a list of posts written in Markdown and uses templates I’ve written to convert it into a website. I think this ease of publishing has helped me write more in 2020, even compared to Medium, which I was using before. This part is the only part of my writing workflow that currently takes place on a laptop (and not a mobile device) – it’s slightly easier for me to proofread and correct mistakes, and manage the website codebase, on a laptop.
I’ll push the change live, and draft up some copy for me to share on my social media about what I wrote and why. I’ve learned over the years that the best times for me to share my writing is either early in the morning, before everyone gets started in their day, or late at night, where everyone’s winding down their day. I’ll usually share a blurb with a screenshot of the post or a table of contents, to give everyone a glimpse of what to expect.
Epilogue
These days, a well-received post from me gets around 400-500 reads over time, with the average post getting around 250 reads. My post on the Lua programming language was read 500 times, and “technical sympathy” just under 400 times. Most of my readers (around 70%) are from social channels, usually Twitter.
People usually read one post, and if they don’t close the tab afterwards, they’ll check out the posts tab for my other posts, or go to my main page. So I try to keep the copy on my home page updated and focused on what I want people to know about me, after they’ve read something I’ve written.
I used to worry about the fact that the topics I write about are all over the place. One post, I’ll be talking about the reality of a life amidst the uncertainty of a global pandemic, and the next, I’ll be doing a 3,500-word deep dive into a programming language’s virtual machine architecture. I used to ask myself, “What if people aren’t interested in both? What if they get tired of what I want to talk about?”
In practice, though, I’ve found that little things like that don’t really matter as long as I write about things that interest me and drive my work. There’s so many places online for people to read about Lua or the pandemic or finding cofounders for your startup; if people are here, they’re probably here because of the way I look at things, whether the subject of that study happens to be technical or human in nature on a particular day.
The things that have proven most important for me in my writing are:
- Being consistent – writing regularly
- Having a high bar of quality for myself, even if I don’t think anyone will read it
- Investing more time thinking about how to communicate an idea, rather than just settling on the first expression of it I think of
Writing consistently has been the single most useful habit I’ve built, and it’s helped me connect with new people and find new opportunities. It’s made me more thoughtful in day-to-day life and improve how I communicate.
Writing is the closest thing to coding in the real world – especially online, it scales your ideas and arguments to other people in a way few other things can. It’s the invisible hand that moves people, and it costs nothing for you to start.
Start writing, and then keep writing. I think it always pays off.
← Build your own programming language
I share new posts on my newsletter. If you liked this one, you should consider joining the list.
Have a comment or response? You can email me.