Writing a Reader-Oriented Blog Article about Your Work

Most people don't write because it seems like a difficult thing to do. For some people, it's their lack of confidence that keeps them from writing out their thoughts. In this article, I have tried to explain why you should write, and put together some hints to help you get started today.

Writing is one of the most difficult tasks for people working in tech. But, have you realized there is an abundance of writing on any given technical topic on the internet. While most developers and designers don't write much, they love to help other developers who are stuck in a problem or looking for ideas to achieve a goal. Hence, tutorials and how-to guides are everywhere. Most authors like to write about the current project they're working on. They share their ideas, describe their methods and in some cases, write a detailed tutorial to follow their lead. Even if you haven't written much, you have definitely read a lot of tutorials. You've come across hundreds of answers on the forums and probably never replied to the questions that you know the answer to. There are already more than enough answers to all the questions, and there are tutorials for everything, right? Wrong.

While there are hundreds of thousands of articles, not all articles have the depth they need. Unfortunately, the blogging world is crumbled by the authors' desire to rank on the search results page. Articles are now filled with unnecessary keywords, irrelevant information, and a lot of links to other articles on the website to improve "internal ranking". Add some useless illustrations on the top of the article only to have a good-looking thumbnail when the post gets shared on social media, and you just created a typical blog article. There are wonderful people who write in-depth articles about their work; unfortunately, search engines are pretty much fooled by the tricks of bloggers who just write for the sake of content publication. In this world ruined by bloggers who seem to write about everything in tech, you can write much better about your craft than anyone else.

What to Write

Write to express your opinions. Write to break the stereotype. Write to tell a story behind the problem you tried to solve for weeks, and finally did. Write about the technology that fascinates you even if you've not mastered it yet. Write your opinions on stuff that come across. You don't have to be right or perfect. Your writing is your own story, so it will definitely be opinionated; it will not make everyone on the internet happy. It will certainly bring in criticism; some people will correct you and encourage you. There's so much to gain by just writing out what you did this week, and what you're fascinated by. Share something that you're proud of even if it's not groundbreaking.

How to Write

Don't write just for the sake of writing. There are bloggers out there for that. There are content creation houses that are constantly monitoring the internet searches for trending keywords to write half-baked articles for the content-hungry web scrapers of the search engines. If you don't have anything to write about, then just don't write today. If what you're currently working on is trivial, and can be summarized in a single paragraph, don't just stretch that into a story. The bottom line for an article is something like "Defining a Custom Brush in Photoshop" or "Using Reverse Proxy to Serve Node.js Application." Anything simpler than those should not make into articles. They should go to your notes, or as a reply to the questions on the internet forums. When you think a few of those ideas can be combined into something substantial, you are ready to write.

The Title

The first thing you should think about is the title. Since you're writing for humans, not for search engines, make your title as specific as you can. Making the title too general may be tempting to attract more readers, making it concise is what you should do. Forget the keywords, remember your readers. The title section must describe in one sentence what you're trying to achieve and how. If it's a story or an opinion, mark it as "Story: your title" or "Opinion: your title". If it's about solving a problem, include both the problem and solution in the title. If it's a tutorial, include the primary tools and technologies you'll be using.

The Excerpt –  "Too Long, Didn't Read"

It's a great idea to include an excerpt of your writing before you go into the details. The excerpt serves the same purpose that an abstract of a research paper does. This section is a single-paragraph explanation for people who don't have time to skim through the article. Include the introduction, problem statement, as well as solution in this section. The excerpt helps your readers what the article is about, and decide whether to read the full of it. Don't ruin the experience of your readers by adding phrases like "keep reading till the bottom to..."

The Introduction – Give some Context

Introduce the topic to the beginners, or describe the problem statement here. You can also use bullet points after writing a bit about the subject first. Target this section for all kinds of audiences, including your colleagues, interns who just joined the company, or someone working on a similar project as you did. Explain what this article is about and what it is not. Also, tell what kind of background knowledge is required to understand this article. You can also add some hints to some relevant reading. If your article's title is "Building a Simple In-Game Chat Using Socket.io in Unity," introduce Unity, Socket.io, and tell the basics of networking in Unity. Don't explain "why" here. Don't tell "how" here. Introduce the terms that you will use and the technologies that you are going to introduce.

The Why Section – Explain the Problem

This section complements the introduction section by telling the "why" question about your story. For instance, if your article is about "optimizing the performance of network calls in Unity," this section should tell your readers why they should optimize the performance and what can happen if they don't. If your article is about "creating visually appealing screenshots to improve app store conversion," this section should describe why you should create visually appealing screenshots and what kind of performance improvement you have seen after re-designing the screenshots. Bring facts, experiences or references to research articles here. Don't just go "this is important brr..." with your assumptions. Be precise, concise and stick to the facts. Since you only write about your past work, this should not be a problem. For an article about building a simple chat service, you can explain why to use Socket.io instead of Websockets, and why to make it yourself instead of using a third-party chat solution, etc.

The How Section – Explain the Procedure

This section is the most crucial. Add as much detail as you can so that the readers can fully understand your solution and follow along. Remember these things while explaining the procedure to your readers.

  • Use simple words and phrases; don't use complex vocabulary. Assume your readers are beginners and have never heard of any technology you're using.
  • Write everything in a flow, so the instruction/story is easy to follow. Step-by-step guides might help. Don't combine multiple instructions into a single sentence; it might confuse your readers.
  • Include screenshots wherever applicable, and remember to highlight the important sections in the screenshot image.
  • Remember to erase/hide explicit, unappealing or confidential information from screenshots and diagrams.
  • Include explanations, example code and images directly in the article instead of linking to a third-party website. The website might be gone someday, rendering your article incomplete.
  • Remember to redact personal information, credentials, domain names, etc., from the example code.
  • Always write a caption for the code block or the attached media.
  • Explain the screenshots or code in a line or two to give some context.

Suppose your article is about designing a low-poly 3D car and importing it to Unity for a game. In that case, you need to explain everything from designing the low poly model to importing it. Briefly describe the involved steps like creating the model, like the tools used, menu items to look for, etc. Then tell a bit about unwrapping the UV maps. Then an introduce the most common formats to export the file. Then, explain the steps involved in importing the model to Unity. Make this section so easy to understand that a beginner can follow your instructions to achieve what you did.

The Discussion – Alternatives and Edge Cases

Do not assume everything goes as planned when someone follows along. There could be some race conditions (edge-cases), which you have to brief. While you should include the most common edge cases in the "how-to" section, this section is reserved for the details of the edge cases. Include alternate example code, screenshots showing errors and warnings, and alternative step-by-step guides if required. Recommend alternative methods to solve the particular problem, if any. Discuss the things that could go wrong in the process. This section should cover everything that's not covered in the how-to section.

Wrap Up – Discuss the Final Results

To wrap up your article, explain the final output or summarize the story. Wherever possible, present the final results as a source code, an animated GIF, or an image, whichever is more illustrative. Give your closing thoughts and leave some hints about where to look for more information about this topic.

Continuing to Write

Do not make writing a routine. Make it a hobby, and write for your readers even if there are few. Someday, somewhere, someone will discover your article; your writing will shape their opinion and help them understand the topic better. They'll move on to the next article, and never look back again but somehow there will be a part of you inside them forever. You, the author, will always be a part of them. Isn't that fantastic?

Keep writing!