Technical Writing: From Idea To Article

1. Define the Goal of the Article and Start Researching¶

First, I try to define as clearly as possible the goal of the article. Sometimes, the goal is to give the reader a starting point for further researches. In other cases, the goal is to explain a certain thing, e.g. a programming language specific behaviour in great detail. The important thing at this point is to specify the goal. Otherwise, no single-minded working on the article is possible.

When the goal is clear, I start researching. Research is always involved, even if I am already familiar with the topic I want to write about. This not only ensures a good quality of the article but helps me extend my knowledge, too. I do not want to miss anything.

Make sure to read a lot and not only a single article from someone else. This way, you can check, whether or not your idea is good or your original understanding is correct. Furthermore, it saves you from unconsciously quoting phrases from someone else.

2. Create a Mind Map¶

The second step involves creating a Mind Map. It helps me bring my thoughts into a structure. On top of that, it serves as a rough outline later on as well. Let's have a look at a sample Mind Map for my article about Python's configparser-module:

As you can see, the centre of the Mind Map is the title of the article. In most cases, it is not the final title but simply an identifier, which helps me determine the topic of the article at the first glance. Each major branch represents a possible section of the article. A single branch may be split up in multiple sections or multiple branches get merged into a single section. It is just important to understand that each branch helps to bring structure into your thoughts and recognise missing aspects.

The leaves of each major branch are facts or pieces of information, which are worth mentioning in the article. While filling the branches, questions arise a potential reader may have. If you cannot answer them directly and put down another piece of information, you have a starting point for another research round.

To summarise: The Mind-Map-step helps to order your thoughts and identify possible knowledge or structural gaps. Creating the Mind Map may take a couple of write-research-rounds. When you have your final Mind Map, you can start with your first writing walk-through!

3. First Writing Walk-Through¶

With first writing walk-through, I refer to writing the first draft of the article. At this point, I do not care too much about the wording, grammar, and the like. The Mind Map is a good assistant here. Make sure to have a friendly writing environment and do not think about finding the right words straight at the beginning. Instead, focus on getting things done.

4. Implementing and Describing the Proof-of-Concept¶

If the technical article includes a sample project or Proof-of-Concept (PoC), which is created in the second part of the article, make sure to focus on the theoretical part first. After finishing it, implement the sample project and start writing the description for it afterwards. From my experience, it is far easier to have a working project, describe it afterwards, and fine-tune the wording at the end, instead of writing the whole article at once and implementing the PoC afterwards or vice versa.

5. Proofreading¶

The last step is proofreading. It is an essential part to ensure the quality of the final article. Proofreading should be a multistage procedure.

Usually, I start by reading the article again and focus on the structure and content of the article. Are all statements made the way, I want them to be? Is the structure easy to follow? Are there possible questions a reader may have which are not answered yet?

In this first stage, a lot of re-writing happens. To make sure that I am the least biased, I do this generally after a few days went by. Consequently, it is easier to discover structural gaps.

In the second stage, I focus on the language. Are the sentences easy to understand or are they too complex? Can I use synonyms for certain words or phrases? Are grammar and spelling correct? While Grammarly can help here, it is good to do it on your own as well. This is because automated checks cannot identify and handle edge cases very well.

At this point, my proofreading part is done. Next, I send the article to others for proofreading. I try to send it to people who represent my audience best and are interested in the topic. After getting feedback and another reading iteration, it is time to schedule and publish the article!