How to write articles that people want to read

Here are a bunch of recommendations that the ‘In Plain English’ team consider to be best practices when writing articles that your readers will find engaging and easy-to-read

Sunil Sandhu
Mar 18 · 4 min read

Titles and Subtitles

  • Please make sure your piece has a title and a subtitle.
  • Take time to consider a compelling subtitle. Don’t just settle for whatever is automatically generated from your opening sentence.
  • Verbs in titles should be direct. An example of this would be “How to Create a JavaScript Library”.

How to

  • “How to” should be formatted with a lowercase “t.”
  • If your title includes “How to,” there is no need for a question mark at the end (e.g. “How to Include an External Library in Your React Code?”).

Code Formatting, Gists, and Links

  • Variable names, file paths, URLs, directory names, class names, and values should be code formatted like this. They should not be bolded or italicised unless they are also code formatted and you’re doing it for emphasis. You can code format something by highlighting it and hitting the ` key on your keyboard.
  • If your code is longer than 10 lines, please put it in a GitHub gist with the proper file format. Create a public gist, paste that URL into your Medium piece and hit enter and it should render in your piece. (Note: Medium currently has a bug where it only renders 11 lines of the Gist in Edit mode. The gist will look fine when it’s published.)

Header Images

  • Welcome readers to your piece with a pleasant cover image.
  • Make sure that your piece has a header image with proper credit. Sites like Unsplash are great places to find free-to-use imagery. They make it easy to cite your source, too.
  • Please don’t use offensive or shocking imagery such as people screaming, clowns, or other images that a reasonable person might not want to look at.
  • Always cite your images unless the image is so common that it’s basically public domain.
  • Don’t make an article that doesn’t include at least one image that Medium can use as an accompaniment. Articles without a suitable image look terrible when they are promoted on Medium’s homepage.

Other useful suggestions:

  • Half-baked articles look bad. If you cannot be bothered to take the time to write your article in a way that has good structure, good punctuation, good spelling, and good formatting, what makes you think that somebody is going to take the time to read it?
  • Take pride in your work. Your writing is an extension of who you are as a person, especially in a professional context. If you are writing about code, it is likely that you have aspirations to work with software, or already do. The words you write represent that, so make sure you do a good job of representing yourself!
  • Your article as a 2–3min read time. Have you definitely covered everything that your article needs and your readers expect?
  • If in doubt about those any of those three previous points, go ahead and read your own article back. Consider whether you thought your article was good enough for other people to spend time reading. Hopefully it is! 🙂
  • Don’t overuse emojis!
  • Don’t use more than one exclamation mark. You’re not writing a comic! But if you are writing a comic, it’s probably fine to write things like “this!!!”
  • Please don’t format the starts of paragraph to super-capitalise the first letter. It just looks stupid.
  • Are you writing about a topic that has already been covered a hundred times by other people? If so, are you really adding anything new to the topic or are you just trying to demonstrate that you know the topic? Give this one some careful consideration and be sure to frame your article accordingly.
  • If you have a website, company, newsletter, or another call to action, please be subtle in your advertising.
  • If your piece has multiple parts to it, please link to those other parts in each piece so the reader can follow the full series.
  • Consider including a Resources section at the bottom of your piece with any useful sources you’ve cited in your piece.
  • Take the time to tag your article sensibly. If your article is about React Hooks, consider tagging it with the core subjects that make up your article “React”, “JavaScript”, “Programming”, and two other suitable tags. Don’t bother tagging it with “Reacthooks” or something similar, because people aren’t searching Medium for that.
  • Thanking the reader for reading your piece in your conclusion is a nice sign-off, but is not mandatory. They spent part of their day with you and your work, it’s always a nice way to say goodbye.

Sunil Sandhu

Written by

Software Engineer, Editor of JavaScript in Plain English, Editor of Python in Plain English

JavaScript in Plain English

Learn the web's most important programming language.

More From Medium

More from JavaScript in Plain English

More from JavaScript in Plain English

How to Secure Your API With JSON Web Tokens

More from JavaScript in Plain English

More from JavaScript in Plain English

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade