How I Write Refactoring ✍️

And why writing in public is one the best resolutions you can make this year.

Hi everyone and Happy New Year! 🎉 By deciding to publish an article every Friday, little did I know I would send one on Christmas Day and one on New Year's Day 😄

In the last couple of weeks I have spent some time reflecting on the past 12 months.

For the first time I had a true, honest retrospective, thought deeply about things that worked, things that didn't, and made some concrete plans for 2021.

While doing so, it was immediately clear that starting Refactoring has been one of the highlights of the year.

It's been so for several reasons:

  • 📚 It forced me to read and learn more about my practice than I ever did. It's inevitable when you have to write a new essay every week.

  • 🧠 It cleared my thoughts about topics I write about. Like Paul Graham said, writing is mostly about thinking clearly.

  • 🤝 It expanded my network enormously — I met a lot of great people because of Refactoring, and conversations are easier because we have this rich, common ground to start from. Writing is really networking for introverts.

  • 💸 It could turn into a business someday — it doesn't hurt that many successful writers, such as Lenny, Monica, and Dan and Nathan, have been able to make a living out of similar setups.

In hindsight, writing in public seems such a no-brainer that I wonder why I haven't started before.

Yet, very few people I know write regularly — or at all.

This article wants to inspire you to do so, while also providing a practical process to get started. I would be so happy if you set this as one of your new year resolutions!

Very few people write

As you may guess, I speak of Refactoring with many friends, and I often suggest them to start writing as well. By now, I think I spoke to enough people to have a representative sample of the excuses everyone makes for not doing it.

They mostly boil down to two:

  1. ⏳ "It takes too much time"

  2. 🤷 "I am not good at writing"

Let me debunk these for you 👇

⏳ “It takes too much time”

I spend 5 hours a week writing.

It's one hour a day during workdays, and weekends are free.

I don't know if it's a lot or a little, if I am fast or slow, but it's consistent every week. To me, being consistent is the most important quality because this way I can plan my time around it.

From idea to publish, I write in 6 steps (+1):

  1. 🔖 Take notes

  2. 💡 Decide what to write about (30 mins)

  3. Six Questions (30 mins)

  4. 📌 Outline (1 hour)

  5. 📑 Draft (1 hour)

  6. 🔍 Review (2 hours)

  7. 🚀 Publish

These steps follow a very top-down approach that:

  • Prevents me from falling into "perfectionist" mode and spend too much time on details.

  • Makes me understand early on if writing about a topic it's worth it or not.

  • It gets consistent results in predictable time (again, the most important thing).

Let's dive in! 👇

🔖 Taking notes

Taking notes is the Step 0, and easily the most important.

It doesn't account against the overall writing time because it's not something I plan for — I just do it whenever I read something, which might be in the evenings, weekends, or whenever I feel like doing it.

Your notes should be the building blocks for your articles, so you never start writing something from a blank page.

If you do it right, writing a new article becomes natural because it is the continuation of the prep work you have been doing with notes.

In Engineering we know that whenever a task feels daunting or too big to be addressed, we should split it into more approachable items. Notes do just that for writing.

So, take notes while you read, and take them the right way.

💡 Decide what to write about

Articles should be like paths through your notes, just expanded and exposed linearly.

Look at your notes, look at what you have written in the past, draw connections and decide what to write next.

It also helps to draw a big picture of the field you are writing about. In my case, I often write about Engineering Management, and I tried to list all the sub-topics that are relevant in my area. This way I have a better idea of what I can cover that I have never talked about, and the connections with what I have already written.

❓ Six Questions

After I have decided what to write about, I answer six fundamental questions to help clear my thinking about the article. These are:

  1. What is the most important point?

  2. Why is that the most important point? (what can you achieve with it)

  3. Why should people care? (what's the benefit)

  4. What is the easiest way to understand the most important point?

  5. How do you want the reader to feel?

  6. What should the reader do next?

I slightly adapted them from a fantastic thread by Shreyas.

This is the moment you realize if your article works or not. You should be able to answer these questions in 30 minutes, and you should be happy with the answers.

At this stage, if you happen to change your mind and scrap everything, you have only lost half an hour of work.

📌 Outline

This is the step where you outline your whole article as bullet points.

I copied this approach from James Patterson's Masterclass. You know, the guy who has written more than 70 books and is the best-selling author in the world 😅

For a 400 pages book, he starts by writing a ~25 pages outline, and then uses it to write the draft.

The outline should present all the main points linearly, in very short sentences and in the same order you would write them in the final article. Just, super short.

And you should force yourself to go fast, to avoid writing full sentences like you would in the draft (I am guilty of that). I spend no more than 1 hour to write it.

I like writing the outline as tasks on Notion, so I can cross items off when I put them later into the draft.

The outline is also invaluable for extracting content for Tweets and social media sharing.

📑 Draft

This is the step where you move as fast as possible from the outline to a "prose" version of the article.

You should take the bullet points and write them better, in a way that is enjoyable to read.

If you did a good job with the outline, and you are targeting something around 500-1000 words, you can do it in a hour.

Yes, one hour! This is the magic of the outline: if you do it right, the draft almost writes by itself.

🔍 Review

Take the draft and polish it in the time that is left until publishing.

I spend about two hours in review, which is about as long as writing the outline + the draft.

During this time I mostly cut things, to keep the post within 1000-ish words. I also improve the style and polish the illustration (which I usually sketch during the draft phase).

People often refer to "second draft", "third draft" and so on, but to me it's a bit more blurry — I just keep editing until it's Friday and I have to publish.

🚀 Publish

When the time comes, just take what you have written and publish it.

And by "when the time comes" I mean you should publish the same day, same time, every time.

Give yourself a cadence — it might be weekly, or bi-weekly, but make sure you treat it as a hard deadline.

🤷 “I am not good at writing”

Writing in public can be daunting if you have never done it before. But as with most things, It's just a matter of practice.

Here is some advice if you are just starting:

  • Write in your own language — many believe they should either write in English, or not write at all. This is bullshit, of course. Write in the language you feel more comfortable with — the value is in the process and the learning, and you will find an audience in almost any language.

  • Start by curating content — if you are not comfortable with writing full essays, you can start by suggesting content to read and listing resources for your niche. Over time add your own commentary, and bits of written material from you. You will build confidence faster than you expect.

  • Go slower — take the writing process, and extend it on a larger time span (e.g. two weeks instead of one). Feel free to spend more time on the steps, but make sure to respect the goals that you set.

📚 Resources

Here are screenshots of the intermediate materials for this article! I try to lead by example 😄

  • 🖼️ Six Questions — this article’s goal is conveying that writing is an activity that can be engineered and made predictable, like many others. Convincing you that writing is one of the best decisions you can make for your career, and you don't have to be "gifted" or anything to do it. Just keep doing it over and over, and you will naturally become good.

  • 🖼️ Outline — you will see that the outline doesn't match 100% the final article. That's normal. The outline is a guide that you follow most of the times, but while you are writing the draft you will likely change some things here and there. You will cut something, change the order of a few items, and so on.

I schedule my writing time in 25-mins “pomodoros”, and usually spend two of them every workday. Writing every day at the same time, for the same duration, really helps me building the habit. Here is a screenshot of my Todoist:

Other useful resources:

  • Blogging for Devs — it's an email course and newsletter for developers and technical people who write, or want to start writing. It's incredibly useful and I learned a lot from it.

  • How to Take Smart Notes — I keep recommending this book to everyone. It's probably the third or fourth article in which I link it! The importance of taking good notes can't be overstated, not just for your writing, also for your learning and personal growth in general.

That's it for this week! I hope this can help you to make a new year resolution about writing 😄 let me know what you think, via email or in the comments! 👇