Writing technical articles: tips for programmers

As a programmer, you might find writing articles is unnecessary. But, in fact, the better programmer you are — the more people need to hear from you about your best practices, achievements, and advice. In this material, you’ll find out the reasons to write, the steps to take and the ways to write well.

Why should you write articles?

Have you ever googled yourself?
Being associated with experts is a good practice. When people read your articles on the internet, they recognize you as a professional and trust you more.

So why to write?

1. Publicity.
2. Self PR, build your portfolio.
3. It works for your company’s reputation (if you work for one).
4. Simple knowledge sharing.

Topics

Write about your experience…
…Experience related to your work.

If you are a PHP developer, nobody expects you to write about Elixir. However, you might tell about your Elixir learning curves or discoveries.
On the other hand, as a developer, you can also reveal your personal points of view or the insights from your daily working routine. Many people nowadays are interested in devs' personal motivation, hacks, and approaches.

Research

Check if somebody wrote about the same things before. If yes, there’s no need to create another related material unless you have:

• Updated (new) version
• Controversial (you do not agree on a previous point) version
• Details

Don’t write the same as someone else has written before.

Find as many related materials as you can, explore them, compare.

Naming

After the research, you should come up with a unique but clear name that indicates the purpose and context of the article.

Bad examples:

1. Roundup #58: Orleans 3.0, Snitch, What’s Your Problem? Next 5 years of ASP.NET Core
2. The One Programming Language to Rule Them All
3. Suffering From Technical Debt?

Why do I consider these examples to be bad? The first one is too long and consists of too many keywords which makes it less specific. Two other examples don’t give you a clue what exactly this material will be about.

Good examples:

1. Ensuring healthy Node.js program using watchdog timer
2. Adaptive Components & Parent-Driven Behavior in Angular
3. How to Make HTTP Requests In React

Names should be more specific, but not too long. From these examples I considered ‘good’, you can highlight the main keyword phrase and the purpose of each article. At the same time, they are not long.

Article structure

While there could be many different ways to organize your content, the user usually expects the text to be created in a certain way. This is a standard for article structure you might follow in attempts to engage your user and present the information in a most relevant way:

1. Title
2. Abstract
3. Introduction
4. The Body: Code, Examples, Pictures
5. Conclusions/Summary
6. Future work /References

The last part is usually helping you to connect your material with the rest of the texts presented in your blog or publication.

Code snippets & pictures

The more quality topic-related pictures you include — the better.
If the article is related to code — insert some code snippets. Use CodePen or its analogs.

Tags & keywords

Keywords are in need because with their help search engines take visitors to your webpage.

If you write about React.js, you should add the following tags: ReactJS, JavaScript, programming, software development, web development, web, UI, open-source (for example).

To search for appropriate keywords you can use several available online instruments.

For empowering your article with keywords try:

• moz.com
• app.neilpatel.com
• trends.google.com
• keywordtool.io
• wordtracker.com/scout

Put the most relevant into your text.

Tags are important to relate your material with the other materials devoted to the same topic.
Use at least 5 tags to indicate the technology, product, methods, experience, and so on.

Language and grammar

Nobody’s perfect. When you are inspired by your topic you will certainly make some typos in your text. And this is the best case. To make your words and sentences correct and readable:

1. Double-check every sentence.
2. If you are not a native speaker (I talk about the English language) translate your sentences if you doubt the correct meaning.
3. Use Grammarly (or other similar plugins that aimed to correct your text).
4. Make sure you use correct terms and phrases.

Also, you might use idioms, but understand the proper case of use.

Pro tips

• Use present tenses. (This means you are currently working with the technology/method/approach you’re writing about). Past tenses also work but only if you apply to the particular experience.
• Avoid lengthy, complex paragraphs.
• Expand all acronyms on first use.
• When providing data (numbers, facts) — always provide the source of information.

Examples

Here I’ll show articles I found good to follow and inspire with.

• Machine Learning for Everyone
• A pretty good summary of Lean, Agile, Scrum
• I created the exact same app in React and Vue. Here are the differences.
• Learn git concepts, not commands

Follow them

These people represent their projects and companies, they are engineers who write texts on a daily basis:

https://dev.to/ben — Ben Halpern, creator/founder/webmaster of http://dev.to

https://overreacted.io/ — Dan Abramov, a software engineer at Facebook

https://twitter.com/John_Papa — developer at Microsoft, https://johnpapa.net/

https://twitter.com/linclark — Lin Clark from Mozilla

https://twitter.com/addyosmani — Addy Osmani, Engineering Manager from Google

I hope, this material will invite you to a world of writing!
Thank you for reading!