There is a great article on writing high quality posts currently on the feed.

How to write a high quality post on DEV

Ella (she/her/elle) for The DEV Team ・ Aug 20 '21

#writing #howtodevto

It is great and I would suggest going to give that a read. (as you can probably tell, I am being mischievous and stealing post titles from people...again!)

Following on from that post, I am going to expand on a few things and introduce a few more tips for writing high quality posts on DEV (and elsewhere).

This is in addition to the post by @ellativity, not a replacement for it!

The tips in this article are ones I wish someone had given me when I first started writing. Oh and there are a few tips in here that will make you much faster at creating articles too!

Contents

• 1. Use Headings properly
• 2. Create a document outline
• 3. Use my editor if you don't know markdown
• 4. Fill in the blanks and make sure to link to any references.
• 5. Run your article through the Hemmingway App
• 6. Mind your language
• 7. Explain abbreviations and acronyms
• 8. Image alt text, a top tip
• 9. Create a contents section if needed.
• 10. A good cover image is important
• 11. Refine your opening paragraph
• 12. Have a promotion strategy if you want more engagement
• 13. Pay attention to comments (and reply!)
• Bonus Tip: Publish your article on your own site first (if you have one)

1. Use Headings properly

Headings help break your article up and make it easier to digest.

They also help people who use a screen reader orientate themselves in your article.

There are a couple of things to note:

1. headings should start at level 2 on DEV (as your article title is level 1).
2. You should not skip heading levels (see below)
3. When writing your document outline start with the main headings, it will help you organise your thoughts and make writing easier.

1a. Headings example (this article)

In Markdown the number of #s correspond to the heading level.

As such you will see the following structure only uses levels 2 and 3 (more on that after this example).

## 1. Use Headings Properly
### 1a. Headings example (how meta!)

## 2. Create a document outline
### 2a. Headings First
### 2b. Bullet points and curly braces
### 2c. Images list

## 3. Use my editor if you don't know markdown

## 4. Fill in the blanks and make sure to link to any references.
### 4a. Sentence Length
### 4b. Use follow on words / phrases (transitions)

## 5. Run your article through the Hemingway App
### 5a. Use Grammarly or similar


## 6. Mind your language
### 6a. Swearing (I should listen to this)
### 6b. Inclusive language

## 7. Explain abbreviations and acronyms
### 7a. Parenthesis (Brackets) method
### 7b. Glossary method

## 8. Image alt text, a top tip

## 9. Create a contents section

## 10. A good cover image is important
### 10a. Create your own

## 11. Refine your opening paragraph
### 11a. Also check your closing paragraphs

## 12. Have a promotion strategy if you want more engagement

## 13. Pay attention to comments (and reply!)
### 13a. Fix problems!

## Bonus Tip: Publish your article on your own site first (if you have one)

Notice how the structure is quite "flat". I only use level 2 and level 3 headings. This tends to be better for web based articles.

If you find yourself getting to level 5 headings you should just check you aren't over-nesting information.

2. Create a document outline

This will save you a lot of time and also help your document "flow" nicely.

A document outline is like a framework for the article, once you have it right all you need to do is follow your own structure and fill in the blanks.

2a. Headings First

The easiest way to structure your document is to write down all of the headings first (or at least the top level headings - <h2>s).

This lets you put the sections in the right / logical order and also highlights areas where you may need some more research etc. before you start writing.

2b. Bullet points and curly braces

After you have your document headings outlined the next step is to detail what is going to go in each section.

I have a useful method for you here!

For each section I do:

• 2-5 bullet points on what needs to be said in that section.
• add curly braces ({) around any thoughts that pop into my head such as referencing sources, images / screen shots to include / create etc.

Then once I have added bullet points and curly braces to all the sections I can just do CTRL + F and search for { to quickly see what research I need to do / references I need to get together / screen shots / images I need.

When you come to write your article leave these bullet points and curly braces in until you have dealt with them to make sure you don't miss anything!

2c. Images list

One final thing to note is that I keep my images list separate.

That way I can just search for images all at one time rather than writing a bit, find an image, write some more, find another image.

By not task switching / context switching often you will work more quickly.

3. Use my editor if you don't know markdown

New to writing in Markdown? It can be hard work.

The DEV editor guide is useful, but it does take a while to learn everything.

Don't worry though, I created a bookmarklet that gives you a WYSIWYG!

It is only partially complete, but it has most of the features you need to make writing articles easy!

Check out the editor here:

4. Fill in the blanks and make sure to link to any references.

By now you should have all of your headings planned out, a few bullet points under each heading, a list of research items and a list of images to find.

Do your research first, that may alter your headings etc.

Once you have all your research together it is time to start writing!

4a. Sentence and Paragraph Length

You write differently on the internet to how you would in a book or in an English class.

You should stick to very short paragraphs (1 to 3 sentences).

Additionally you should try to keep your sentences short.

Many people using DEV will not have English as a first language. Shorter sentences make your content easier to understand.

Short sentences are also easier to follow for people with dyslexia etc.

Finally due to screen sizes, short sentences and paragraphs are much more manageable on a mobile screen so you don't get massive walls of text!

4b. Use follow on words / phrases (transitions)

Transitional words / phrases allow a reader to know that a paragraph / sentence is a continuation of a previous one.

For example I just used the phrase "for example" to indicate that this sentence builds upon the previous one.

In addition to providing a nice flow to the document it helps with comprehension of your text (especially as we are splitting it into very short paragraphs so the association between sentences is not as clear).

5. Run your article through the Hemmingway App

Did you know that 1 in 5 people have the reading age expected of a 12 year old (in the UK, Germany and the USA at least...I am sure other Countries are the same).

The Hemmingway App / Editor is a great tool to help make your text easier to understand.

It highlights long sentences, passive voice etc. This helps with the points raised in section 4.

In addition to this, be conscious of the complexity of the words / vocabulary you use.

You do not need to use big words to make yourself sound smart. If you can simplify your language it means that more people will be able to enjoy and understand what you have to say!

The Hemmingway editor will give your article a "grade" based on complexity. You are aiming for grade 7 or below ideally.

Due to sentence length and careful word choices, this article is only grade 3!

5a. Use Grammarly or similar

I need to do this one as my grammar is awful!

Using a service such as Grammarly will help make your article easier to read as well.

This is especially useful if English is a second or third language and you choose to write in English, due to how weird and wonderful English Grammar is!

If I was to write an article in German (which would be impressive given the 7 German words I know), I would look to find a similar service for writing in German.

6. Mind your language

I am glad this isn't a case of "the person who is without sin can cast the first stone". 🤣

I don't follow my own advice here when it comes to swearing.

But there are things to be conscious of, but no fixed rules as such. As I have said before context is key to knowing what is appropriate.

6a. Swearing (I should listen to this)

Ah, who am I kidding, I f***ing love a good swear every now and then.

But bear in mind that if you are going to use swearing in an article, you should put a warning at or near the start for the people who are offended by swear words. Make sure not to swear before that warning!

Oh and don't do what I did...I screenshotted an offensive site I had built for the cover image of the article...and forgot to censor the swear words 🤦‍♂️!

You should also bear in mind that DEV will not promote any articles with swear words in the titles on social media.

Note: if you are not offended by swearing...here is the highly offensive website in question!

6b. Inclusive language

I am not going to lecture you on ableist language (as I know it is such a difficult thing to get right (link to comment I made)), gendered language etc.

Just bear it in mind. Use "they" where you can instead of "he" and "she" (or mix it up throughout your article and try and keep it balanced).

Use language that is acceptable in your culture for describing people with disabilities (and read up what is generally considered acceptable so you minimise the chance of people being offended).

Don't use racial slurs, obviously!

Oh and probably steer clear of politics unless you can take the heat!

7. Explain abbreviations and acronyms

Do not assume that people know what acronyms and abbreviations mean.

People from various backgrounds and various stages in their careers from various disciplines will read your article.

If you are going on about SSR then you need to explain what it is as there are loads of possibilities for what SSR stands for!

Here are two ways you can explain abbreviations and acronyms.

7a. Parentheses (Brackets) method

When you first use an acronym or abbreviation write out the full phrase and then put the shortened version in parentheses.

For example:

In this article we will be using JavaScript (JS) to create a Single Page Application (SPA).

Our SPA will consist of three pages and all routing will be handled by JS.

Notice how I only add the full phrase once. After that you can use the abbreviation for the rest of the article.

7b. Glossary method

If something needs a bit more explanation (or you don't want to slow the pace of your article if there are a lot of abbreviations in quick succession), then a glossary is a great solution.

You add a section to the end of your document "Glossary".

You then have a list of terms followed by their explanations (we can use the <dl> element (and <dt> and <dd>) for this.

You need to then create a hyperlink that points to those terms in the glossary section.

Here is an example for doing this in markdown:

In this article we discuss [HTML](#def-html), [CSS](#def-css) and [JS](#def-js).

## First Heading etc.

[...all of your article content...]

## Glossary
<dl>
  <dt id="def-html">HTML</dt>
  <dd>Short for Hyper Text Markup Language. It is a programming language 😉</dd>

  <dt id="def-css">CSS</dt>
  <dd>Short for Cascading Style Sheets, used to make stuff pretty</dd>

  <dt id="def-js">JS</dt>
  <dd>Short for JavaScript, it was written in 10 days.</dd>
</dl>

Notice how I prefix the IDs with def-, this is just to reduce the chance of collisions.

8. Image alt text, a top tip

When writing alt text on images the aim is to provide information that is relevant in context.

That is why it is impossible to just have generic alt text for an image and use it everywhere.

One way to write good alt text is to imagine you are reading your articles to someone over the phone.

When you get to the image, what information is important so they get an idea of what the image is about, and what it adds to the article.

That is what your alt text should be.

Oh and also, you don't need "image of"...people already know it is an image.

9. Create a contents section if needed.

Right now you should have a beautifully written article, using inclusive language and with great alt text (and possibly a glossary!).

Once you are happy with the article, create a contents section!

Now this is assuming your article is over 1000-1500 words in length (which a high quality article is likely to be).

You do it last because as you write the article the order of sections and headings may change.

I would advise only adding your <h2>s to the contents to keep it from getting cluttered.

I am working on adding an auto contents creator to the WYSIWYG I mentioned earlier.

10. A good cover image is important

The cover image shows on social media and if you article happens to end up at the top of the home feed.

It is also the first thing people see when they open your article.

Make sure the image is engaging and relevant (or branded...)

10a. Create your own

If you write regularly you may want to create a branded template for article covers.

This saves time and also lets people start to recognise your branding and know to look out for your articles.

11. Refine your opening paragraph

Right nearly ready to launch!

Now we do some selfish stuff! We need to optimise our opening paragraph for SEO and engagement.

Now that you have written the article, what will people learn, is there anything fun in the article that would grab people's attention etc?

Also think about SEO. The first 100-200 words in an article are very important for SEO.

Think about key terms, semantically relevant / similar terms etc.

Obviously this is secondary to creating an engaging opening paragraph as read time is important!

11a. Also check your closing paragraphs

Same thing here.

People tend to read the beginning and the end of an article more than any other parts. Yes, I am sorry to break it to you, people probably won't read your whole article (which is why we putting headings in!).

So make sure your closing couple of paragraphs are engaging as well and, if you want people to do something (visit a site, leave a comment, follow you on social media etc.) then make sure you say that prominently.

12. Have a promotion strategy if you want more engagement

I wish I wasn't just starting to do this myself.

Content will get some natural traction on DEV and it may even get shared on social media by a couple of people.

But you need to be in control of your own destiny and not leave it up to others!

Build a following on social media and then make sure that you queue posts on the various social media channels to send out when you publish your article.

It is a case of "the rich get richer" on DEV. If you article gets a lot of likes early on then more people are likely to click into it.

If you get enough likes your article will then sit near the top of the "week" tab, where it will get more likes and views.

All of this increased your chances of a share on social media...which adds more likes etc.

So if you can give your article a boost when you first publish it then you are far more likely for it to do well.

13. Pay attention to comments (and reply!)

Engaging with people who take the time to leave comments on your article (other than "thanks for this" type comments) is important.

It is how you get people to follow you and more importantly the comments are where you pick up loads of hints and tips.

Oh and for the love of all that is mighty please please....

13a. Fix problems!

If somebody pops up in your comments section telling you there are problems with your article and how to fix them then fix them.

There is no excuse, it takes 2 minutes to make a couple of edits.

Also, don't say "yeah I will fix it and then do nothing about it"...such as in this article where I left a comment with a couple of fixes (yes I am calling people out on this now, there is no excuse for leaving mistakes in articles and misinforming people!)

Bonus Tip: Publish your article on your own site first (if you have one)

Just a general Search Engine Optimisation (SEO) tip and only relevant if you have your own site (I still haven't got mine up and running yet!).

Publish articles on your own site a few days before you publish on DEV and other platforms. Even though canonical URLs are meant to make sure you get the link juice etc. it isn't perfect.

If you launch on your own site first and wait for Google to index the page then you are far more likely to get your own site appearing in Google search results.

Conclusion

Hopefully those 13+1 points are useful to you.

If anything isn't clear please let me know in the comments.

Oh and above all, you should

follow me on Twitter

I am about to ramp up my content game on the bird app, you need to follow just for the dad jokes!

Oh and one last thing, if you are wondering why this article has 13 points + a bonus, then these two articles will make sure you are in on the joke!

Oh and these articles have some great examples of what not to do if you want to produce high quality content. Enjoy (silly posts)!