How I Write My Articles
Finally, I can do this, write an article on how I write articles. The circle is closed. I can rest in peace.
It’s finally the moment you all have been waiting for, what this journey was all about: the ability to write an article on how I write my articles. The circle is closed. I can rest in peace.
Part of me is very sorry to be writing this and falling into the cliché. Yet, here I am, sharing it with you. I hope you forgive my vanity.
I believe that writing is a precious skill for any professional. Other people spend a lot of time reading what we write: chat messages, emails, presentations, documentation, etc. We can’t escape writing.
Yet, sometimes writing seems a daunting task, especially when it’s about writing something long. But it doesn’t have to be this way. I devised a process to split the daunting task of writing an article into smaller and more manageable tasks.
> This process allows me to publish a weekly article while working full-time at DFINITY.
I Like Checklists
I always follow the same process. Therefore, I have a default checklist to ensure that each article has finished all the intermediate steps before publication.
It gives consistency to the process and removes the psychological barrier of writing. For example, the task “Write about sockets” is too overwhelming to start immediately. When split into smaller tasks, it becomes more approachable. I also wrote an article on splitting development tasks.
> Splitting a big task into smaller ones is key to my productivity.
I use Roam Research for my Personal Knowledge Management, where for each article, I create one page. On this page, I keep track of all the steps and notes I take along the process.
Any note-taking tool can do. Yet, for this process to work best, it must be a tool with a powerful search.
To write the article itself, I use Google Docs.
Write down concepts, words, sentences, and stuff that comes to mind regarding the article's topic. I aim for about ten to twenty ideas.
For this article, this step could give a list like: "productivity, schedule, week, writing, soft skills, process, checklist, ideas backlog, monthly plan, style guide, tools, writer, editor, planner mindsets, second brain."
This step and the next one are taken from the Second Brain.
The previous “Brain Dump” list is a good starting point to search within my notes. I search for each word and take what is interesting for the current article.
This step is similar to the previous one but with Google. I search for the title (or topic) and review all the results on the first page. Then, I read/skim and add notes to the “Article Page.” Not necessarily only about the topic, but interesting sentences or approaches to the explanation.
Since I still like paper books, if a topic is in one of my books, I look into what’s written there and take notes. An example of this was Creating a Simple Server From Sockets, where most of the notes came from the book Computer Networking. A Top-Down Approach.
After checking the external and internal research, I have enough information in my head about the topic. Now it’s the moment to brainstorm and focus on what I’m going to write. I put down the different things I’d like to discuss, the conclusion it could have, an introduction, etc.
This step brings some structure to the chaotic processes I have been following until now. But not necessarily succeeding.
It’s in this step that I finally structure the article. All the previous steps are primarily chaotic and explorational. This is the first step with the clear goal of writing an article.
For some topics, I jump directly to this step, such as this one. This is because I know the subject very well (I follow my process every week, duh!). But these are rare cases; most of the time, I follow all the steps.
The output of this step is a structure of sections. For example, the outline for this article looked like this:
- Choose a topic - Backlog of ideas, most of them come with comments and links to check already - "Article XXXX" page in Roam. - Brain dump - Review existing content - Research - Brainstorm - Outline - First draft - First review - Second version - Diagrams / code snippets - Confusing explanations check - Third Review - Final Review - Share with editor (friends) - Review after editor feedback - Add to the website
This is the first Outline. Not necessarily what ends up published; it’s a structure to help write the first draft.
This step can still feel overwhelming. So I like to approach it as if this draft doesn’t count, like a brain dump, but with more structure.
I try to write the article in one hour or less. I follow the outline of the previous step and never stop to search for anything, draw diagrams or code anything. If I need a drawing, a code snippet, or even a link, I add it in a comment. I don’t distract myself from writing.
I usually do this step the day after the Outline, leaving time for the structure to sink into my subconscious.
I am not a writer anymore but an editor. Therefore, I never review on the same device where I write the first draft. Instead, I send it to my iPad, where I check it and take notes.
The output is a lot of red color on top of the first draft. But that’s ok.
Then, the article comes back to the writer. I review the changes requested (by myself) and rewrite a new draft. This is not so overwhelming because I don’t start with a blank page.
At this point, the article is more robust and should not have so much red in the following review.
Diagrams / Code Snippets
I always wait until the article is more mature to create the diagrams and code snippets. If I write them too early, I might realize that they don’t fit the content. Or that I missed a point I wanted to make.
Doing it in its own step allows me to read and review the article again.
Yet, some articles start first with a coding project. For example, the sluggish animations: I first built a project, and then two pieces came out of it.
This is a checklist of possible confusing explanations that Julia Evans uses in her writings. I use it because I love her articles, and I think she has a gift for making complex topics seem simple.
An example in this list is: “making outdated assumptions about the audience’s knowledge.”
So far, the reviews have been very informal and unstructured. In this step, I bring consistency to all my articles. It’s similar to ensuring that a codebase always follows the same coding style and design patterns.
For example, I avoid the second person singular (“you”) when writing. Instead, I prefer the first person plural, “we.” Except in the conclusions and introductions, where talking directly to the reader makes sense.
Most of the checks come from On Writing Well, a book I recommend to anyone writing non-fiction.
I also use Grammarly to check the grammar. It helps prevent some patterns which might sound too much like my mother tongue.
I read, yet again, the article, and there should be almost no changes. However, if I add too many, I return to the “Second Version” step. This has happened a few times, but thankfully not always.
Most of the time, there are simply a few changes, and I consider it finished.
Share With Editors (Friends)
Until now, I have been writer, editor, and developer (even illustrator). So, according to all my roles, the article is ready. But, that might not be the case. Luckily, I have some friends who are kind enough to read my article and give me feedback.
So, thanks to Bernat, Limones, Michal, Miguel, Yusef, Jocy, and JC for reading my drafts 🙏
Review Editor Feedback
I only share one article with a maximum of three friends at a time. Then, I incorporate their feedback into the article and decide whether it’s good enough to publish.
In the last months, only one article has not been published and needs an extensive rewrite. But I have four pieces I wrote last year that won’t be published unless I do a significant rewrite.
Add to Website
This is the last and most rewarding step. I add it to GIMTEC. This is done only the week I want to publish it. Normally a few weeks after writing the article. Therefore, I do another review and reassess the quality.
I also have a checklist of steps before publishing. For example:
Check the article tags.
Check title and description metadata.
Add a paragraph thanking the reviewers.
Add a section for the subscribers (if I have news to share or something to say).
After this checklist, the article is ready to be published, and I schedule it for next Wednesday at 5 pm CET.
I don’t do all the processes at once. Instead, I distribute the tasks throughout the week. For me, letting time pass between steps is important to have a fresher approach. The gaps between steps are also important to think about the article. The article lives in my head for at least the whole week.
My weekly schedule looks like this:
Monday: Braindump, Internal and External Research.
Tuesday: Brainstorm and Outline.
Wednesday: First Draft.
Thursday: First Review, Second Version, Diagrams.
Friday: Confusing Explanations, Third Review.
Saturday: Final Review, Share with Editor.
I incorporate the feedback from my friends when I get it, and I add it to the website the week I want to publish the article.
Find Your Own
This is what works for me. One thing I especially like about my process is that each step is not overwhelming. Each step is a maximum of one hour. Splitting the task of writing an article into smaller steps of less than one hour has allowed me to keep writing consistently for almost a year.
Yet, my process might not suit you. You can take just one or a few parts and change the rest.
I have changed the process a lot since I first started with GIMTEC. For example, the last change was adding the checklist of Confusing Explanations after reading the article.
Next year, I hope to write an article explaining the changes I have made to this process.
If you like this post, consider sharing it with your friends on twitter or forwarding this email to them 🙈
Don't hesitate to reach out to me if you have any questions or see an error. I highly appreciate it.
And thanks to Michal and Sebastià for reviewing this article 🙏