DEV Community

Cover image for Start Writing About Code: The Why and How
Netanel Basal
Netanel Basal

Posted on

Start Writing About Code: The Why and How

This article was originally published in

In over three years of writing, and having written over 120 articles, I have decided to share with you some tips I have learned along the way to help those who wish to start writing or are already in the process of writing.

Before we begin, I would like to point out some reasons why one should start writing in the first place.

🤔 Why You Should Start a Blog

The first reason being that one of the things that cause developers satisfaction, is knowing that the information they share has helped someone else.

A second reason is that writing an article requires a deep understanding of its content, so in the process of doing so, we become more professional.

The third reason is that my articles are my reference whenever I need to develop a new feature or solve a bug whenever I've forgotten how to do so.

The last reason is the ability to create a name for yourself in the community, which is a nice thing in and of itself.

Hopefully, by now you're convinced you should start writing, so allow me to give you some tips:

✌️Don't Give Up

One of the common responses I get from people who start writing is "I only had 20 views", or "I only got one like."

Let me tell you something: It took me three years of writing to get to where I am today. If you do not keep moving forward and creating useful materials, it will stay that way. You mustn't give up.

📤 Share Your Articles

In order to get to know you, especially at the beginning of your journey, it's important to publish the articles you create wherever possible.

Share them on Facebook groups, LinkedIn, Twitter, or any other relevant place. If you don't do that, the chances of readers being introduced to them are very slim. Once you have enough followers, you can skip this part.

👮 Choose Your Content Wisely

A crucial decision to make is what your articles should be about. The articles that get the most views are those that solve a problem for a large number of people. Try to offer unique content to the reader, and avoid writing about obvious things.

🤓 Select a Good Title

The article title is one of the most important decisions you'll make, for two reasons: First, a good headline attracts more readers; Second, a good headline will show up in many relevant search results.

Always think about what the reader would write in the search input, and build the title based on that. Your article's exposure will be much more significant if it's on the first page of Google search results.

😟 "But English Isn't My Native Language"

Unfortunately, there are a lot of very talented people who want to share their knowledge but are deterred from doing so, because English is not their native language.

But at the end of the day, we all speak one language: code. Even if you're not the most articulate English speaker, don't be shy, just write. If the title is good and the code is interesting, people will understand. So don't worry too much about it.

Personally, I have often encountered technical articles written in various languages, such as Russian or Chinese. I saw an interesting title, ran Google translate, and learned a few things from them.

Furthermore, these days you can get online proofreading services for a small amount of money. So the bottom line is, do not let that deter you. The more you write, the better your English will become.

💪 Improve Your Writing Skills

Learn from others: The only way to get better at writing is to read other people's technical books and articles. Pay attention to their methods, opening sentences, and styles of writing. Then see how your writing can improve as a result.

👂 Get Feedback

Ask for feedback from as many of your co-workers and colleagues as possible. I'm sure you understand what you've written, but that doesn't necessarily mean it's evident to others.

😞 ״But Someone's Already Written About It״

If someone has already written about a particular subject, that doesn't mean you shouldn't write about it either. There is a chance that readers will benefit from your explanation and examples.

✋ Ignore Rude Comments

Along the way, people will comment on your articles. Some of those responses might be rude; My advice is simply to ignore them, and not to take them personally.

✍️ Tips for Writing:

  • Keep it simple. Try to avoid complicated phrases. People love to read clear and concise language. Most importantly, be yourself.

  • It's better to write one long article than divide it into several parts. The reader can stop at any point and get back to it, so you don't have anything to worry about.

  • Try to have a fair amount of code and text - I encounter many articles that have lots of text but very little code, or vice versa. In many cases, it discourages the readers and they abandon the article.

  • Create a proper division into paragraphs, add punctuation marks and periods where necessary.

  • Using emojis is always lovely and valuable 🦄

  • When possible, before you go into the technical parts, show the readers an illustrated example of what you're going to create. Use an image, gif, or any other means. There's a chance that this is what will attract readers and keep them reading on.

  • When you add a code section to an article, make sure it's nicely formatted.

  • Don't add code blocks as images. It is very annoying and prevents people from being able to copy the code.

  • Try to add the final result at the end of the article, whether it's via a Github repo or something like Stackblitz.

Hope these tips helped inspire you… now go write 😎

Top comments (1)

carlillo profile image
Carlos Caballero

Thanks @netanelbasal ,

Very good advice for all those who have started writing about our projects.