Writing for the web is a skill, like any other, that can only be perfected through practice. I’ve been writing on this blog for two years now, and creating content for other sites before that, and I like to think I’m pretty okay at it – though there are always ways to improve! In this article I’ll share a few tidbits of wisdom that I’ve acquired over the years, which might help you if you’re starting to blog, or even making the switch from writing for print.
While these are written with technical content in mind, they could apply to many different types of web content.
Write while it’s fresh
Rachel Andrew recently tweeted the following advice, and I couldn’t agree more:
The best tutorials are very often written by someone who has just learned a thing. It is very easy to forget what it is like to stare at the docs, wondering how on earth you get started, wishing someone would guide you through it.
— Rachel Andrew (@rachelandrew) April 15, 2020
Writing that article while the experience is fresh in your mind will no doubt make it all the more relevant to the reader. It also means you’re likely to be more excited by the topic, making it more engaging to read.
I try to follow this advice, but don’t always succeed!
Don’t worry about typos (too much)
Your readers will forgive your spelling and grammar mistakes, especially if the content is valuable. Don’t let imperfect grammar hold you back from publishing. Try to be more thorough when it comes to checking code examples though – in my experience it can be frustrating trying out a code example from an article and wondering why it doesn’t work.
Also, don’t worry if you don’t feel like you’re a “natural” writer. People are rarely judgemental, and can look past the fact that you haven’t quite found your writing style yet. You can only improve with practice, so don’t let it put you off.
Get to the point
Readers want to know as quickly as possible whether an article is going to be relevant to them, and therefore worth investing their time in. Try to sum up what they’ll actually take away from the article in the first paragraph.
Write in short paragraphs
One way in which the web differs from print is that it can be harder to hold a reader’s attention. Plenty of people scan an article before deciding if it’s worth their time to read, and a wall of text can look intimidating and put some readers off before they even get started. Short paragraphs make this easier.
Relevant headings for the different sections are handy for this purpose too.
Explain your terms
Using a new term for the first time? Explain to your readers what you mean? Using an acronym? Spell it out for the first instance in the article – after that, you’re generally safe to use it throughout.
Include lots of links
It’s often useful to include a link when using a term that might be unfamiliar to some readers. For example, I often link to the MDN (Mozilla Developer Network) documentation for a CSS property or specification, especially if it’s something fairly new. Or, if I’m mentioning another developer by name, I’ll include a link to their website or Twitter bio.
Not only that, but anyone who wants to dive deeper into a topic will appreciate links to your sources, as well as demos and sites they might find helpful. A list of resources at the bottom of an article (or relevant section) can be handy.
(Links might also be good for SEO. I don’t have any actual data on this, and this isn’t the reason I include them, but I’m told that’s a thing. Please don’t cram your article with links just for SEO purposes though, as irrelevant links will be more hindrance than help.)
Write for your readers, not your ego
This might sound obvious, but it’s sometimes easy to forget when you’re mid-flow. Often I catch myself writing a sentence that sounds eloquent to my ears but, on a second reading, does not sound helpful to someone coming across the information for the first time.
Using a bunch of jargon (especially without explanations), or complex language where a simpler explanation will do the job better, can easily alienate your audience. When I’m writing, I frequently ask myself: “Am I writing this sentence because it’s helpful, or because it makes me sound clever?” If it’s the latter, I delete it.
Acknowledge your shortcomings
No-one knows everything about a topic (with a few exceptions!). You don’t have to be an expert at something to write a useful article about it – many of the most useful articles are from a beginner’s perspective. But make it clear to your readers where the limits of your knowledge lie, (and include links to other sources, if possible), so that they can make an informed judgement about your advice or approach.
Resources and acknowledgements
This post was part-inspired by an excellent Twitter thread by Manuel Matuzović, which he then followed up with a blog post to summarise.
People much smarter than me have written in much more depth on the subject of technical writing – they also publish highly successful blogs, so definitely take note!
- Advice For Technical Writing by Chris Coyier, published on CSS Tricks
- Pitching Your Writing To Publications by Rachel Andrew, published on Smashing Magazine
- Just Write by Sara Soueidan