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.
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.