I edit a lot of technical articles over at Smashing Magazine, and write a good few myself. Over the years I’ve absorbed a lot of information in terms of what works when writing tutorial content, and one thing I keep coming back to is that you need to know who the ideal reader of your piece is.
Technical articles can’t all start from explaining to the reader how to create an HTML page, therefore they all bring with them some assumed knowledge. The level of assumed knowledge might be basic HTML, or for an advanced piece might involve a whole compendium of languages and tools. There is always something you expect your reader to know. Define that for yourself before you start.
- What languages does the reader need to know, and to what level?
- What tools, frameworks or libraries should they be familiar with?
Once you have that list, you can refer back to it as you write the article. You may even be able to think of someone you know who is that ideal reader. As you come to explain something, which refers to one of the things you expect the reader to know, you don’t need to over explain. If the thing you need to refer to isn’t in that list, then give a more complete explanation, perhaps linking to another article for more detail. Your list helps you to explain the things that need explaining, and avoid filling the article with things your reader should already know.
Your list should also be part of your introduction to the article, explain to the reader that to follow along they need to already know certain things. You could always offer a link to an introduction to those subjects. If the article is for real beginners, then be clear about that too, it’s helpful to know right away that something has been written for a person like you.
Writing for the experienced
When writing for experienced practitioners, you need to write something that offers value over that person just looking at the documentation. Your list of assumptions, and imagining your ideal reader can help here. An experienced person is likely to be able to get to “Hello, world” from the product docs. Therefore an article for that person needs to share more than an introduction. Good things to include are tips and tricks gained from your own practical use, the sort of thing you don’t get from the docs but from actually using the tool within the constraints of a real project. The docs often don’t go into how the tool can be combined with other tools or techniques, how it can fit into an existing workflow, or how you can transition from an older way of doing things to this new fancy way. All of these are good topics for the more experienced reader.
Writing for the beginner
When writing for beginners to a technology, be especially careful with your assumptions when considering your ideal reader. It’s incredibly offputting if you think something is for beginners and then realise you need to understand an entire toolchain just to get started. Avoid using words like “just” and “simply”, include good resources for getting started with any prerequisites.
However remember that many readers will be beginners to this technology but not beginner developers. A great example is when writing about the modern JavaScript ecosystem. A reader might be a perfectly competent JavaScript developer, but they have never used a framework like React. They don’t want to read something that speaks to them as if they have never written JavaScript before, but they will need a lot of background information about how the ecosystem now works to be able to start to work with React. As a writer, it is a useful practice to keep a list of really great introductory articles to various subjects. You can then use those as links to help people with the things you don’t have time to cover in your piece.
So, next time you start writing, or creating a presentation, or tutorial video, first consider the question who is this for? Answering that will make all the difference.