20+ Lessons I've Learned Writing on DEV for 4 Years
Tags: writing, beginners, career, meta
Published: 2021-06-29 12:05:44

{%- # TOC start (generated with https://github.com/derlin/bitdowntoc) -%}

- [1. First, get started 🎬](#1-first-get-started)
- [2. Do not Bury the Lede ⚡️](#2-do-not-bury-the-lede-️)
- [3. Brainstorm on Paper 📝](#3-brainstorm-on-paper)
- [4. Talk it Through With a Friend 🗣](#4-talk-it-through-with-a-friend-🗣)
- [5. Learn Markdown 📚](#5-learn-markdown)
- [6. Add a Table of Contents ✅](#6-add-a-table-of-contents)
- [7. Be Liquid 💧](#7-be-liquid)
- [8. Use emojis 😄](#8-use-emojis)
- [9. Use #️⃣tags ](#9-use-tags)
- [10. Upload images on GitHub 🏞](#10-upload-images-on-github-🏞)
- [11. Start a series ⏭](#11-start-a-series-⏭)
- [12. Originally published on your own blog 🔗](#12-originally-published-on-your-own-blog)
- [13. Generate your blog with Stackbit ❤️ ](#13-generate-your-blog-with-stackbit-❤️)
- [14. Add a cover image 🌅](#14-add-a-cover-image)
- [15. Write in a Markdown Editor ✍🏻](#15-write-in-a-markdown-editor)
- [16. Push to a private GitHub repo 👨🏻‍💻](#16-push-to-a-private-github-repo)
- [17. If English is Not Your Mother Tongue... 🇬🇧](#17-if-english-is-not-your-mother-tongue)
- [18. Publish Early, Publish Often 💡](#18-publish-early-publish-often)
- [19. Publish now, Share later 📣](#19-publish-now-share-later)
- [20. Beware of Vanity Metrics 👎🏻](#20-beware-of-vanity-metrics)
- [[UPDATE] Even more tips](#update-even-more-tips)
- [What About You?](#what-about-you)

{%- # TOC end -%}

I've written 69 articles in the last 4 years and I'm eager to share with you what I've learned so far.

I'm by no means done learning, so if you have additional tips for writing good articles, _the comments section is all yours_!

## 1. First, get started 🎬

If you have not written your first post, nothing you would read here matter much.

So make sure to get started, and if you are unsure how, I have a guide for you!

{% link https://dev.to/jmfayard/yes-you-should-write-that-firstpost-481 %}

## 2. Do not Bury the Lede ⚡️

Your first sentence should contain what is most important in your article.

Here is a test you can use to find out whether you bury the lead in your articles:

Can the first sentence of your article be used as a good tweet to introduce your article?

This one is rather good I would say:

<img width="652" alt="Home___Twitter" src="https://user-images.githubusercontent.com/459464/123141307-89db6700-d458-11eb-9504-7a389261d96e.png">

This one is rather bad:

<img width="609" alt="Home___Twitter" src="https://user-images.githubusercontent.com/459464/123141118-54cf1480-d458-11eb-80b7-59916027334b.png">

## 3. Brainstorm on Paper 📝

To write a good article, you need a good topic, either one you are excited to write about, or one requested by the public(*). You need a good title, and a mission statement of what you are trying to achieve with the article.

I've found it easier to find multiple good titles than to find only one. By that I mean that coming up with a good title when I'm exhausted after finishing an article is hard. On the other hand, if my relaxed brain focuses only on coming up with topics, titles and mission statements, my creativity kicks in. Your mileage may vary but for me nothing beats pen and paper for brainstorming.

(*) Bonus: https://answerthepublic.com/ is a cool tool to find out what the public wants to read. Enter your topic and you will be greeted by the most common questions asked on Google.

## 4. Talk it Through With a Friend 🗣

Words always come easily - said no writer, ever.

A strategy that works wonder is to:

1) write a shitty first draft as fast as possible, with no structure or formatting getting in the way.

2) talk it through with a friend: "... and what I find very interesting is... / ... what I really wanted to say is that...".

3) now write the article you wish you had discussed with your friend.

## 5. Learn Markdown 📚

If you haven't learned Markdown yet, put that on your TODO-list because you need it to format things nicely.

It won't help you only on DEV but also on GitHub, StackOverflow, Blogging software and many more websites.

I won't elaborate on this because @yechielk has done a wonderful job explaining markdown, so bookmark this:

{% link https://dev.to/yechielk/these-lifehacks-will-change-the-way-you-write-markdown-3651 %}

## 6. Add a Table of Contents ✅

One flaw of Markdown is that there is no build-in way to say: "Hey, please insert a table of contents here".

If you use Visual Studio Code, I recommend [Marky Dynamic](https://marketplace.visualstudio.com/items?itemName=robole.marky-dynamic) with which you can insert and update an automatically generated table of contents. 

This is how the table of contents for this article is built.

## 7. Be Liquid 💧

DEV has liquid tags that allow to preview a link 

```
{% post https://dev.to/jmfayard/things-i-ve-been-writing-on-dev-to-22io %}
{% github jmfayard/refreshVersions no-readme %}
{% tag kotlin %} 
{% comment 2d1a %}
```

{% post https://dev.to/jmfayard/things-i-ve-been-writing-on-dev-to-22io %}
{% github jmfayard/refreshVersions no-readme %}
{% tag kotlin %} 
{% comment 2d1a %}

There is a friendly doc available in the editor.

<img width="407" alt="New_Post_-_DEV_Community_👩💻👨💻" src="https://user-images.githubusercontent.com/459464/123160900-0a0cc700-d46f-11eb-96c0-5ef144390981.png">

## 8. Use emojis 😄

Break the monotony of walls of text by adding emojis as often as they make sense.

I used to think that was ridiculous, I changed my mind. 

## 9. Use #️⃣tags 

Take some time to discover what tags are available at https://dev.to/tags

Technology-related tags are pretty obvious: `#javascript #css #java #python...`

There are cross-cuttings tags you want to be aware of:

- `#beginners` if your article is accessible for them.
- `#productivity` if you have tips to be more productive.
- `#career` for anything related to jobs and careers.
- `#showdev` to show off what you've built.

Some tags have non-obvious rules you need to be aware of:

- `#discuss` is for eliciting community responses but is not appropriate for blog posts.
- `#help` is to ask for help, not to be helpful to others.
- `#opensource` is for discussing the philosophy and practice of open-source, it's not for promoting your open-source project.
- `#watercooler` was hard to understand for me, because I have lived in France where slightly off-topic discussions happen around the coffee machine, and in Germany where they happen in the Biergarten. No watercooler involved.


## 10. Upload images on GitHub 🏞

You can get your point across with fewer words using screenshots, annotations, shapes and sketch.

I use [Skitch](https://evernote.com/products/skitch) for that, happily so.

One thing I don't like is uploading pictures in the editor.

As a work-around, I have a GitHub issue where I drag&drop all my pictures

<img width="1043" alt="Markdown_drag_drop_pictures_·_Issue__1_·_jmfayard_writing" src="https://user-images.githubusercontent.com/459464/123161614-e433f200-d46f-11eb-8b59-ba6f82da5781.png">

## 11. Start a series ⏭

Instead of writing one yuuuge article, you can divide & conquer your thoughts in a serie of articles.

Make sure to use the **Series** feature so that the different parts are linked together.

<img width="657" alt="New_Post_-_DEV_Community_👩💻👨💻" src="https://user-images.githubusercontent.com/459464/123162355-cdda6600-d470-11eb-8aa5-18810d100517.png">


## 12. Originally published on your own blog 🔗

As much as I like DEV, I want to stay the owner of my content.

For this you need to set the **Canonical URL** to link to a copy hosted on your own blog. This will tell Google and other search engines where the article originally comes from, and prevent them from flagging the ``dev.to`` article as duplicate content (thus banning them from the search results).

<img width="575" alt="Edit_Post_-_DEV_Community_👩💻👨💻" src="https://user-images.githubusercontent.com/459464/123452164-70fcbe00-d5de-11eb-8041-50e7d7a20825.png">

## 13. Generate your blog with Stackbit ❤️ 

You don't have an own blog yet?

Wait no more, you can generate it from what you publish on DEV.

[https://dev.to/connecting-with-stackbit](https://dev.to/connecting-with-stackbit)

This is what I use for https://jmfayard.dev/ 

I love how low-maintenance it is!

## 14. Add a cover image 🌅

If you have spent time and effort in your article, you don't want it to to look like a boring link when shared on Twitter/Slack/Whatever. 

Therefore you need a cover image **of size 1000x420**.

(I always forgot this information).

I'm a backend guy so I struggled to produce decent cover images.

My favorite strategy is to write programming code and transform it in a gorgeous image with **https://carbon.now.sh/**

This is what I've done in [Android's billion-dollar mistake(s)](https://dev.to/jmfayard/android-s-billion-dollar-mistake-327b)

![](https://res.cloudinary.com/practicaldev/image/fetch/s--Wpnu0qiV--/c_imagga_scale,f_auto,fl_progressive,h_420,q_auto,w_1000/https://thepracticaldev.s3.amazonaws.com/i/zamboudckyy9j54eylr4.png)

If you can draw, you have a super power that you should use here!

I can't but my wife produced this great cartoon in [“What is your current salary?” is a red flag that you don’t want to work here](https://dev.to/jmfayard/what-is-your-current-salary-is-a-red-flag-that-you-don-t-want-to-work-here-3aji)            

![](https://res.cloudinary.com/practicaldev/image/fetch/s--dLMLCjoO--/c_imagga_scale,f_auto,fl_progressive,h_420,q_auto,w_1000/https://dev-to-uploads.s3.amazonaws.com/i/b9se7wfxtxhgdz4qnqkw.jpg)

If you publish often on the same topic, [Canva](https://www.canva.com/) is a good tool to produce a branded image where you only have to change the title.

This is what I used in [How to learn Kotlin: browser vs IDE, books vs tutorials, for newbies and Java devs - DEV Community 👩‍💻👨‍💻](https://dev.to/jmfayard/best-ways-to-learn-kotlin-from-scratch-or-from-java-with-books-or-tutorials-online-or-in-the-ide-52cm)

![](https://res.cloudinary.com/practicaldev/image/fetch/s--ZQz-YEdv--/c_imagga_scale,f_auto,fl_progressive,h_420,q_auto,w_1000/https://thepracticaldev.s3.amazonaws.com/i/ae05lypwluxrmxq53w3n.png)

Last but not least, @pjijin has made a good cover generator. This is what I used for this article:

{% post https://dev.to/pjijin/generate-cover-image-for-your-dev-posts-easily-27co %}

## 15. Write in a Markdown Editor ✍🏻

DEV has its own editor at https://dev.to/new but they won't take offense if I say that a stand-alone Markdown editor is much better. 

Thanks to Markdown being a standard (not really, but that's off-topic), there is a variety of editors you can try:

* [Visual Studio Code](https://code.visualstudio.com/) is good as always, and it has a spell-checker.
* [Notion](https://www.notion.so) is a solid choice.
* [Typora](https://typora.io/) is my current favorite for its distraction-free interface.

## 16. Push to a private GitHub repo 👨🏻‍💻

Once you start to use a stand-alone Markdown editor, the logical next step is to push your changes to GitHub. Or Gitlab or whatever you prefer.

I got this tip from @john_papa 

> Saving my content and making sure I do not lose it (2 of my goals)  are reinforced by creating a GitHub repository for my content. I prefer  this to be private as it contains a lot of my writing. I also organize  my repository in a way that makes sense to me. I can find my articles  quickly, modify them, iterate on them, and move along.

{% post https://dev.to/azure/how-i-write-online-articles-1lfb %}

## 17. If English is Not Your Mother Tongue... 🇬🇧

Being able to write a complete and easy to read article with no dumb mistakes in a foreign language is such a hard multi-years journey. 

Even after 25 years, I'm far from being perfect.

I feel your frustration.

And I highly recommend this article from @vtrpldn who share useful tips to cope with the challenge:

{% post https://dev.to/vtrpldn/technical-writing-tips-for-non-native-english-speakers-4fno %}

## 18. Publish Early, Publish Often 💡

It is often exhausting to polish an article until everything is ready.

My tip: hit the **Publish** button _before_ you are ready.

What do you fear? It's not like thousands people will read it the minute you publish it, that never happens.

Having something published releases some of the tension involved in finishing the article.

Now read again your published article, and incrementally improve what needs to be corrected.

## 19. Publish now, Share later 📣

It is often exhausting to publish an article, and I will advise you against sharing it right after it's done.

I have a friend who writes epic super long stories, and I was surprised and jealous that he managed to write 1.000 additional words to promote his work on Facebook and LinkedIn afterwards.

His secret was that he gave time to his brain to relax. He "finished" an article on Monday, published it on Tuesday and shared it on Wednesday.

## 20. Beware of Vanity Metrics 👎🏻

Blogging platforms, including DEV, gives you access to the number of views in your article.

It's in the human nature when you see a number to want to see it big, and growing.

I want to have a word of caution here: this is a hedonic treadmill that is not good for you. 
As soon as you hit a target, you get used to it, and disappointed when you don't hit it again. 

It's dangerous to have goals that are not meaningful. I would suggest to focus on the impact you have, on meaningful conversations, etc.

{% post https://dev.to/helenanders26/the-trouble-with-blog-post-views-and-vanity-metrics-2al5 %}

## [UPDATE] Even more tips

{% embed https://dev.to/jmfayard/comment/265je %}

## What About You?

What challenges have you faced trying to write regularly?

What strategies did you use to overcome them?

Any article you want to share?

_If you want to write to me, there is a standing invitation at https://jmfayard.dev/contact/_