Writing for the web
Tags: devjournal, webdev, tutorial, html
Published: 2022-08-08 21:55:00

_Originally published [on my blog](https://robinwinslow.uk/writing-for-the-web)._

Some things to consider when writing content for the information superhighway.

Please don't think it's only worth writing if you have incorporated all this (or any other) advice. The best thing is to just get your writing out there -  don't sit on it, don't be a perfectionist. But if you can easily incorporate any of this advice then so much the better.


## Audience

* Human beings
* Search engines (Google)

![Search engine market share](https://lh3.googleusercontent.com/G-GXQIBAyHD2Ps-9Wi6bQs4ZvRIE3zl7Dkiyl5PvkuAbHEIRey8vcMg2ZxwXCyfvLt2Bg0jUFi_VwrxTz3phLeCCOc-9zpS2zuSNcl7K_rWF9vFbuTG87Do-Yjf2Xupusk16iye5)

Don’t try to “trick” search engines (black-hat SEO) - algorithms change all the time, and if you are caught using “black hat” techniques you will be penalised.

Search engines approximate human beings. The best SEO is good writing for the web.

But many SEO best practices are also good principles for readability and accessibility:

* liberal, well-structured headings
* diverse vocabulary
* liberal links
* informative link text


## Write for scanners

Although there is definitely an audience for high-quality, in-depth long reads, the web medium is much more suited to a fleeting, busy audience with a short attention span.

> [“People are not likely to read your content completely or linearly”](https://www.nngroup.com/articles/how-people-read-online/)

Advice on writing for scanners:

* Use clear, noticeable headings and subheadings
* Place information up front ([Inverted pyramid structure](https://www.nngroup.com/articles/inverted-pyramid/)) - nothing like academic writing
* Use standout features in writing: · bullets, **bold text**, [links](https://www.nngroup.com/articles/writing-links/), “pull quotes”, 📊graphs etc.
* Use plain language, use succinct language. Write efficiently (use [https://hemingwayapp.com/](https://hemingwayapp.com/))


## Attention-grabbing titles

How clickbait can you go?

![Ubuntu design blogs leaderboard](https://lh5.googleusercontent.com/0PCMJLnYUhka9i4sWD8-Ev1QtX0rhgI5MAbRZmk4DPP71yvWeJ0kzs0U4Q__PnqdSknSK2szGD4iEIFVfuG3xo3m0jAHIqESUu9yXjZYISE3I0cvJecN4Vu-MYonsaZ81yZWaLbF)


Classy click-bait: Mention the hook (“We reduced our images by 60%”).

Trashy click-bait: Withhold information (“here’s why”, “you won’t believe what happened next”)

“Top X” type articles (listicles) - easy to write, a simple marketing trick. Not clickbait, just very common

**Don’t **just use the topic as the title (e.g. Ubuntu Online Tour; Regex basics).

**Bottom line:** Summarise the article as richly as possible in a few words; make sure to include the hook


## Use headings liberally

Well structured headings are important for SEO, and also help users scan the page easily.

The more headings you can use the better.

As with titles, tell a story with the heading. Summarise the content below richly, don’t just write the topic.


## No introduction necessary

It’s easy to agonise over how much background to put into your writing. Do you need to explain the very concept you’re talkin about before you even begin?

I’ve heard it advised that you shouldn’t do this. Just start writing from the point you’re at. The only people who will really appreciate your writing are those who are at the right level to get it. And these are probably the only people who will click the link to find your article in the first place.

Those people are your core audience. Don’t waste their time.

## Diverse vocabulary

Look for opportunities to phrase things in different ways. 



* An aesthetically pleasing way to write
* Helps aid readers’ understanding, as one way of saying something might not make sense to them
* Helps people find your article through search engines, as they might try searching using various different terms

E.g.: Summarise your article one way in the title, another way in the meta description and a third in the introduction.


## Link early, link often

The web revolutionised referencing - this is hugely underappreciated and underused.

Using links liberally is essential to both your own SEO and to the health of the web at large.


> ["PageRank is NOT Dead"](https://ahrefs.com/blog/google-pagerank/)

Especially look for opportunities to link to your own content.

Links are also a great way to call attention to key pieces of information within your writing.


> [“Eyes Are Drawn to Links”](https://www.nngroup.com/articles/writing-links/)


#### Carefully consider link text

The exact text you use for your link is very important.


> [“Poor link text hurts usability, accessibility, and seo”](https://www.nngroup.com/articles/writing-links/)

Search engines use the link text to determine what a target page is about. Diversity is important here again - if you link to a piece multiple times, describe it a different way each time.

It can be worth adding [titles](https://help.emarsys.com/hc/en-us/articles/360016353478-Links-Link-title-attribute) to your links to describe them even better.

**Never ever say “click here”. **


## Helping people find your content

If you want people to find your writing, share it on social media, using every account you can.

Make sure to share your article on Twitter, Facebook etc. And also [hacker news](https://news.ycombinator.com/) and [Reddit](https://www.reddit.com/).

For blog articles, write them first for your own site (you should benefit from your content), but it’s well worth reblogging them into a centralised blogging site. These sites have large communities and will promote your in lists of new articles on there. Examples:

* [https://medium.com/](https://medium.com/)
* [https://dev.to/](https://dev.to/)
* [https://www.tumblr.com/](https://www.tumblr.com/)
* [https://hashnode.com/](https://hashnode.com/)
* [https://substack.com/](https://substack.com/)

Make absolutely sure you link back to your own site.