Hello there, I couldn’t write something for a long time, but here I am writing a blog about blogging.
I already have written an article about blogging a couple of years ago: How I write articles. But, I thought of providing a framework that helps to structure the process of writing an article not just for beginners but also for experienced writers.
Read more: GARLIC: The Secret for BloggingContents
Introduction
Writing is an art, but it is more of skill as well. This means, with enough time and focus, it also can be learned, just like any other skill. Then we don’t have to think too much about what to write because the words will come to us like a stream. And, it’s like telling a story and taking the reader on a journey!
I’m not going to talk about creative writing in this article mainly because that’s very subjective. So, let’s focus on non-fiction writing, specifically “technical articles”.
In my opinion, it’s always good to have a proper structure and process to write a technical article because that has to be precise and informative. So, here is the framework I came up with to make it easier.
G.A.R.L.I.C.
My wife loves garlic and she puts it in almost all the food we cook, but I can’t say I love it. But, I can highly recommend GARLIC for article writing.
GARLIC means:
- Goal
- Audience
- References
- Language
- Informativeness
- Composition
Goal
Before even start writing our article, we should define the goal of our article. We should be able to answer the question “what should it do?” and ideally it should only have one answer. If we have two or more answers for that, it usually means that we should write separate articles for them, or it’s better to break our article into parts!
So, how can we define the goal of the article?
It usually is the message we expect to deliver to our readers. This usually goes in the title of our article and should be explicitly mentioned in the first paragraph. This sets the expectation for the reader on what they’re going to gain from our article. This aspect is very important to maintain the engagement of our readers because most of them won’t read past the second paragraph if the goal of the article is not clear.
Examples:
✅ Getting started with Dataflow flex templates
✅ Apache Beam vs. Apache Spark: What’s better for you
✅ How to test your Python code with PyTest
⚠ How to test your code
⚠ How to deploy your app
❌ Calling functions to do stuff
❌ How to fix bugs
It’s not enough to write a compelling title, it’s also important to explain the goal of the article to the reader as soon as possible, ideally in the first paragraph itself. We can check the bold text of the second paragraph of this article itself for a more practical example 😉.
So, set the goal of the article, add it to the title, and explain it in the first paragraph itself.
The exception is when the title is a click-bait, where it’s not explicitly clear what the article is about, but makes the reader curious enough to open and read it.
Examples:
✅ Why I picked this JS framework for my website?
✅ Buggy code? Here’s what you should do!
I don’t usually use these types of titles because I like to be explicit about the content and my blog is NOT a gossip website 😉.
In any case, make sure the title and the first paragraph clearly explain the goal of the article.
Audience
The next thing is to define the target audience for our article as it determines how (deep) we should explain concepts. Depending on the audience we have to decide how deep we should explain the concepts and the examples we use.
Let’s take the article title I added in the examples: “Getting started with Dataflow flex templates”.
For this article to make sense, the reader MUST know what Dataflow is. This means they should have some experience with GCP and Apache Beam. This ultimately means that a basic to intermediate understanding of ELT jobs and distributed data processing is required. Only then this article would make sense.
Then we should decide whether we should explain these concepts (at least briefly) or should mention them as prerequisites for the article. It’s also good to explicitly mention the target audience and the level of expertise/experience recommended for understanding the contents of the article in the beginning. It’s also good to provide links to learn more about these prerequisites because it reduces the burden on us to explain everything. (More about this in the next section).
The audience also determines the examples and analogies we should choose to explain a concept. Imagine we still wanted to write the article “Getting started with Dataflow flex templates” for an audience who never used Dataflow (or Apache Beam) but knows about ETL (or distributed data processing). How would we explain what Apache Beam is?
Apache Beam is a distributed data processing framework that can be used to process huge amounts of data from different sources in both streaming and batch manner. It provides an SDK for us to write more object oriented code to write our ETL jobs as pipelines, and most importantly the capability of visualizing and monitoring each step of our pipeline using a DAG (Directed Acyclic Graph). And, Dataflow is a fully managed service provided by Google to run Apache Beam jobs.
What if the audience doesn’t even know about distributed data processing?
We all know we can write some code to process our data and extract information out of it. But, some data loads are quite huge and can not be processed by a single computer. Then, we need a fleet of computers communicating with each other to divide the work load and process them. To cater this, there should be a variety of optimized data structures algorithms to make sure the data is processed efficiently and accurately. Apache Beam is an open source framework which takes the burden of managing resources in this aspect and we only have to specify “what” to do and it automatically figures our “how” to do it.
Of course, we can always give external resources to read without putting extra effort to explain simple topics. However, if we didn’t pick our audience correctly and overwhelm them with technical jargon without explaining them, we’ll lose the audience quite easily!
References
When we write a non-fiction document, it’s extremely important to give references to support our facts. In technical articles, we can provide official documentation, SDK or CDK links, API Specs, and even official blog posts from organizations. However, I wouldn’t recommend adding random blog posts as references since it might have a hit on the credibility of our article and might even cause deadlinks if they decide to bring down their article.
As explained in the Audience section, it’s not feasible to explain every single thing in our article, because otherwise, our article will become a thesis! We all know how much we hate writing those, and nobody actually read them! Therefore, I’d recommend choosing a fine balance of explaining and using references for further reading.
Since almost all tech blogs are now online (either as a webpage or a PDF), we can add in-line Hyperlinks to redirect the reader to the external resources instead of adding Bibliography type references that are mostly used in research papers [1].
To learn more about Flex Templates, please read this article which explains the basics.
Sometimes we may (have to) use images, diagrams, or any other media to help our content and make sure we ALWAYS give references to the origin/owner. It not only shows our gratitude towards the owner but also helps us to evade copyright claims. However, don’t forget to read the licensing policy of the content we’re adding to our article and make sure we are allowed to use them.
Regardless of whether they hold information related to the article or they’re just filler images, we MUST add references to everything which are not ours.
Language
Then the next important aspect is the language we choose to write the article. It doesn’t only mean picking which language to use as English, Sinhala, or German, but also the tone and the vocabulary to use.
Language
Of course, we should first decide the language to write our article and it entirely depends on our target audience. The reason I’m writing this in English is that I want to bring this to as many people as possible since English is (widely) used in many countries. If I were to target my content to the people in Sri Lanka, I most probably would write this in Sinhala (only because I’m not proficient in Tamil). However, I’ve seen that most of the tech articles are written in English because it’s widely used in the tech community.
Tone
Then, we should pick a tone for the article. It means whether the article has more of a formal tone, semi-formal, or informal. The words we can use for different levels heavily vary on our style and personality. I myself am not a native English speaker and I’m most comfortable writing in (semi-) informal language. That’s why I usually have a very loose sentence structure and a few sarcastic comments here and there. I believe most tech people find this (semi-) informal language easy to understand, so I usually write like that. I also try not to use complex or rare words because my goal is not to show off but to be as much information as possible.
The tone can also depend on the purpose of the article as well. It can either be informative, positive, negative or many other moods. This mostly depends on our Goal and the words we choose to use.
For instance, I always used “we” and “our” throughout the article to mention the things to do rather than using “you” and “your”. If I had used “you”, it might add a commanding tone to the article and the message might not get delivered properly. When I say “we should do this and that”, the reader feels that we are on the same side, and not some random person on the internet telling them what to do.
Grammar
Regardless of which language we use, we should try our best to adhere to the grammar and spelling of the corresponding language we’re using. This also depends on the tone of the article since different languages have different ways of conveying a message and the tone is inferred from the grammatical structures we use.
For instance, English is a very simple language compared to more complex one such as German. But still, we can still write with proper grammar and it can be made comparatively informal with a good choice of words (I might be wrong because I’m not a native English nor German speaker). However, a language such as Sinhala (my native tongue) is a bit different in this aspect. We don’t speak with grammar, and it would sound super weird if we do. So, if I were to write an article in Sinhala, I wouldn’t write it with 100% grammar, and use a slight variation of the verbal dialect.
This also depends on the goal and the audience of our article because we should carefully choose our language to avoid any backfiring.
I highly recommend using a spellings and grammar checker to proofread the article since it can save a lot of time. I personally use Grammarly and the free version already offers quite a lot of valuable features.
Informativeness
It doesn’t matter how many words or references we use to write our article in the best possible language tricks if our article doesn’t give any value to the reader. This aspect should be taken into consideration in the Goal phase itself, but we have to always evaluate our article to see whether it gives any value.
We should make sure our article provides some novel information to the audience that they can’t find anywhere else. Our article shouldn’t be a collection of references to other references nor a summary of them. It at least should include our personal experience or opinions to help the reader expand their knowledge.
A good question to ask ourselves is: “Would I read this article?“
If the unbiased truthful answer is yes, we’re on the right track. If not, we should update the article or in the worst case even discard it.
Composition
With all the above aspects in the right place, it wouldn’t add any value if we randomly place all the information throughout the article. It should have a proper structure and flow!
Structure
Any article should have a start, a body, and an end.
- Start
Clearly explains the goal of the article and the expected outcome. - Body
The contents of the information as clear as possible. - End
Summarize the content by providing a highlight.
Since an article can be long (just like this one) and having only these three parts can easily overwhelm the reader, we have to break it down into smaller sub-sections. Each sub-section can explain a logical sub-part of the article and can follow the same Start-Body-End structure recursively.
For instance, this article has several sub-sections, and some sub-sections even have their own sub-sections. This helps the reader (you) to easily see the scope of the content and it makes understanding and grasping concepts much easier compared to having all information as a huge pulp.
Moreover, people don’t usually read an entire article word-by-word, but rather hover through it to extract only the important ones. That’s why we usually scroll down to the accepted answer in Stack Overflow, even without fully reading the question 😂. Therefore, adding sub-headings to clearly separate parts of the content not only helps the reader but also helps us to formulate our idea better.
Self-Referencing
As mentioned above, many people don’t read every word in our article. Some people just read the headings and then pick the right sub-section, some people only read the summary, and some people don’t read it at all 😓. However, if they land on a sub-section and see something they didn’t read, it’s always good let them know that we already covered it or we’re going to. Just check the beginning of this paragraph!
We can simply yet sneakily do this using “as I mentioned in the XYZ section” (even with a hyperlink), or “this will be covered in the ABC section”. Then the reader can easily navigate to that particular section if they need to refer to it.
This also helps a lot to keep a nice flow throughout the article which also gives cues to the reader that they should spend more time on our article.
Length
We also have to be careful about the length of the article because some people easily get overwhelmed by seeing the length 😉. This also depends on the scope we’re planning to cover, type of the content, and the target audience. If our article is a tutorial with descriptive examples, people won’t mind spending half an hour reading it. If it’s just an announcement or a comparison, they need the information as soon as possible with a minimum number of words.
So, we have to pick the right structure and words to make sure we don’t exceed the comfortable level of reading duration.
Tips
And, now we explored GARLIC and how it can help to structure our articles, let me give some tips to make sure we write our blog the best way possible.
Remove unnecessary words/sentences
The last thing we want is for our article to be super long and make the reader leave. So, it’s very important which words we use, but mostly which words we can remove.
Something I usually do is ask the question:
“Will it still hold the meaning if I remove this word/sentence/paragraph?“
If the answer is Yes, I remove it straightaway or try to adjust it in a way that I don’t need that word/sentence/paragraph”.
This can save a lot of space and can reduce the length of the article quite a lot.
Review
We should always review your articles! We can write the first draft and share it with friends (ideally in the target audience) and get their feedback. If we don’t have friends (that you can do this with), we can always re-read our article after a couple of days with a fresh mind. Trust me, it’ll help us to find a lot of mistakes that we never saw while writing or reading right after. I usually re-read my article half a day later and fix any issues with grammar or composition.
Summary
In this article I explained GARLIC: the framework I came up with myself, that helped me to structure my blog posts, and still, convey the intended message.
It’s simple:
- Goal
- Audience
- References
- Language
- Informativeness
- Composition
With GARLIC and the tips I gave, I hope you’ll be able to write better articles in the future. As always, feel free to drop a comment and/or share this with your friends.
Here is a potato for you!
