Writing beginner level tutorials

I’ve been writing books and articles for around ten years. However, like most of us who write about web design and development, I didn’t set out to be a writer. I simply do interesting things in the course of my job and then write about them. A lot of my writing is essentially aimed at beginners and I thought that I would note down a few of the things that I have found to work really well when explaining unfamiliar technical concepts to people. The same approaches work well in my experience whether you are writing for people unfamiliar with a subject, presenting to them at a conference, or training them in a small group setting.

Your job is to get your reader to the point of asking the next question

You cannot teach your reader everything you know about a subject, somehow getting them to the same level you are in the course of a book or article. Your job is to get them to the point where they can implement something at a basic level, and understand what they might need to search for to be able to take their knowledge to the next level. Trying to explain too much – for example going into alternate theories of “best practice” or detailing edge cases where a technique might not work is best kept for a more advanced tutorial.

Address a solution in the context of the problem your reader might have encountered

This is a really helpful way to explain things. As an example, if I am writing about CSS and explaining how to clear floats, I will introduce the subject with an example. I show the reader an example of some elements in a container that has a background colour. After floating the elements the background disappears – what has happened? I can then go on to describe how floats work, and the various methods of clearing in the context of a problem they may well already have encountered, or will encounter at some point.

In the case of online writing, explaining the problem is also very helpful in terms of people finding your work via search engines, as they won’t be searching for the solution – they’ll be searching on keywords relating to the problem.

Demonstrate the simplest cases

Try and make examples as simple as possible, it’s very tempting to show “real world” examples, with all of their inherent complexities. However if there is too much going on in an example, it weakens and makes less clear the point you are trying to get across.

It is often necessary to explain a problem within the context of how it will be used – however making those contexts as simple as is possible will help your main point to become the focus of learning, and avoid the reader becoming confused as to what is actually creating the effect that you are describing.

However when simplifying, take note of my next point.

Be careful not to leave security holes in copy and paste code

It’s not too much of a problem to simplify examples in CSS, however if you are writing about serverside technology then there are levels of complexity that you cannot avoid including. Christian Heilmann has written about the very real issues of showing a cool technique simply, at the expense of security in his article, Teach Them How To Hit The Ground Running And Faceplant At The Same Time?, for Smashing Magazine.

Just saying, “this is not production code” is not enough. People will still copy it and use it as is. Often people don’t even fully read an article that has code in it, they just grab the code example and use it.

Often the best approach is to avoid showing any fully worked code on the page. This stops a person just using the code as is. Show the snippet you are describing and then provide a link to a fully worked and commented download that includes any functions or linked in libraries that will allow the reader to deploy the example in a live site safely.

You can treat included libraries as a black box, meaning that you don’t need to fully explain what they do, more than a couple of lines or a code comment to justify the inclusion and say why it is important. This maintains simplicity and gets round the copy and paste code problem.

Use words and phrases that your reader can Google to find more information

It’s important that you include in your writing the key words and phrases that people could stick into Google in order to find out more. Sometimes this won’t actually be strictly correct terminology, in which case you can explain what something is called and then also say, “often referred to as […]” or even, “you’ll find more information on this subject by searching for […]”.

Short, to the point, question and answer solutions work well

The format that Sitepoint asked me to use when I wrote the first edition of The CSS Anthology was one of short questions and answers, each dealing with a particular CSS topic. The book has maintained that approach right through the the fourth edition that I am currently working on. Sitepoint have used the same approach on several other books dealing with different technical topics and it is an approach that really works well. As a writer or speaker, sticking to answering a question helps keep the solution focused and helps stop you heading off down various tangents. The reader also gets a clear solution to a real problem, so they feel they have a “take away” that works.

Build something that works as quickly as possible

When learning any new subject, getting to the point of having built something that works is really important. It’s at that point you can say, “I did that!” Having “done it” builds confidence. This is especially true when teaching technical concepts to people who don’t feel this is their strongest area. The most important thing you can do for a reader or talk attendee who is feeling outside their comfort zone, is to get them quickly building something that works. Realising that they can do it, that they can understand, will give them confidence to continue and build on those first steps.

I really enjoy helping people make their first steps into learning about a subject. I often hear from people who started learning CSS with The CSS Anthology, who are now excellent front-end developers and could probably teach me a thing or two!

If you write for beginners and have tips to share, add them to the comments.