How to Write a Programming Tutorial
I am in no way a programming or tutorial writing expert but every now and then I overcome a problem or do something enough times that I feel like I have enough to say on the subject and may as well write a tutorial. As I've been writing recent tutorials I have noticed a few things in other tutorials that drive me absolutely bonkers. I decided to write a quick post with some tutorial writing tips for those out there wishing to put what they know up for the world to see and benefit from.
Your Intended Reader
There is a fine balance between targeting the largest demographic and expecting the reader to have some prior knowledge. Obviously you can't start off with a basic tutorial on programming every time you want to talk about a high level programming concept. On the other hand, you definitely don't want to expect too much from the reader. There are often many paths someone could take to arrive at a need for the knowledge provided in your tutorial. Not all of those paths will teach the person everything they need to know in order to effectively utilize your information. Just because you learned how to Mock an object before you learned how to do Unit Testing doesn't mean someone else didn't learn Unit Testing before they learned how to Mock an object.
A happy medium is to usually mention prerequisite knowledge and surround the mention with a link to a resource that would educate them. For example:
"In this tutorial we use Moq to Mock our interfaces."
This way you don't inconvenience readers that understand everything you just mentioned, but you provide quick links to resources about Moq, Mocking, and Interfaces for those readers that need a little more education before diving into your tutorial. Tutorial writing is more than just putting down what you know; it requires some forethought and some research. Despite that fact, it does not take very long to plug a term into Google, find a decent result, and use that as a link. Your readers will be grateful for the extra effort.
This goes along with expecting too much from your readers and is my biggest tutorial pet peeve. Never just throw out an acronym and expect everyone to know what it means. This is even worse than mentioning a concept or technology that the reader may not have heard of; at least with that the reader could Google it themselves fairly easily. Googling an acronym is sometimes a very futile practice. As an example I recently ran across an article that discusses different aspects of unit testing and mocking. In the article I found this paragraph:
Thus it's no surprise that the mockists particularly talk about the effect of mockist testing on a design. In particular they advocate a style called need-driven development. With this style you begin developing a story by writing your first test for the outside of your system, making some interface object your SUT. By thinking through the expectations upon the collaborators, you explore the interaction between the SUT and its neighbors - effectively designing the outbound interface of the SUT.
Nowhere else prior to this paragraph does the article provide a reference to what a "SUT" is. My train of thought was completely derailed and I had to go on a hunt to find the meaning of this acronym. I put the acronym into Google and came across this Wikipedia result. Look at all the different meanings for the acronym. In the context of the article I assume the first one on that list (System Under Test) is the one I was looking for, but I'm still not completely sure. Eventually I will come across it again in another context and I will understand it better, but what a pain in the readers' backsides.
Hot-link your acronyms PLEASE. The software industry is full of acronyms and it can be very confusing to newcomers. It is so important to provide links that explain the acronym you just started using in your writing. At the very least provide the full phrase in parenthesis next to the acronym. The best option is to do both. For example, that paragraph should have looked like this:
Thus it's no surprise that the mockists particularly talk about the effect of mockist testing on a design. In particular they advocate a style called need-driven development. With this style you begin developing a story by writing your first test for the outside of your system, making some interface object your System Under Test (SUT). By thinking through the expectations upon the collaborators, you explore the interaction between the SUT and its neighbors - effectively designing the outbound interface of the SUT.
The individuals reading your article or tutorial should not be pronouncing the acronym in their head. They should be expanding the acronym in their head as they read. Most readers won't bother to go look up the acronym, they'll just power through the tutorial subconsciously hoping to find a context that implies the acronym's meaning. When they don't find such a context the reader will often become frustrated and simply find a better tutorial if they can. Introducing small unknowns in a tutorial makes the reader uncertain. They feel like they should already know something and when they don't they can get overwhelmed and decide your tutorial is out of their league, when in fact all it would have taken was a bit more reading on their part.
Make your tutorials easy on the eyes of your reader. Be specific and detailed. If users ask common questions about a particular step in your tutorial, consider adding in the answer as part of the tutorial, rather than hoping others with the same question navigate to the comment where you answered.
Sometimes even the most simple lines of text can make all the difference in a tutorial. For instance:
"Open up Visual Studio's macro manager and add new macro."
The author of the tutorial may not even think there is something missing, but what if the user has never seen the macro manager for Visual Studio? Make your instructions concise and easily followed:
"Open up Visual Studio's macro manager by going to 'Tools' > 'Macros' > 'Macros IDE...' and then right-click 'MyMacros' and select 'Add' > 'Add New Item'."
The text isn't that much longer and provides much clearer instructions to the reader. Sometimes just finding the menu you are talking about can be extremely frustrating for the reader if you did not provide instructions for how to find it.
Follow Your Own Instructions
There are few things more aggravating than a broken tutorial. Even the most intelligent of readers will want to break things around them when the tutorial they just spent a half hour following turns out to be erroneous. They will almost always think they are doing something wrong at first and repeat the steps in the tutorial three or four times before realizing your tutorial was simply broken and did not accurately represent the task it was trying to help the reader accomplish. The point of a tutorial is to walk a reader through something they've never done before. If the tutorial has errors the reader won't have much in the way of resources to help them correct it as they are obviously not experts on the subject; if they were then they wouldn't be reading the tutorial in the first place.
Triple-check your tutorial. Read it 3 times after you're done. Get a friend to read it if you have to. Even seasoned programmers make mistakes, especially without the aid of their favorite IDE. Most people will not realize your tutorial is faulty until it has already made them angry. They expect a tutorial to be an accurate guide to the desired goal. Naturally they will think they are misunderstanding something when their work fails. The realization that you have not been wrong, the tutorial was, is a painful one and you are not likely to return for more after that experience.
Put a Date on It
Date your tutorials! I can't stand finding tutorials on exactly the topic I was looking for only to find out that the tutorial was outdated and no longer applies. For example, take this tutorial title and pretend it was written in 2008:
How to Integrate Sandcastle Into Your Visual Studio Build Process
The unsuspecting reader might find that title to be exactly what they wanted, but after a certain version Microsoft Sandcastle changed the way it builds documentation significantly and a tutorial written in 2008 would not apply anymore. You can never anticipate what changes are to come when writing a tutorial and you certainly can't be expected to maintain all of your old tutorials indefinitely. So to ease some of the reader's pain when they find an out of date tutorial make sure you list a date on the article.
A date can be more helpful than one might realize. Noticing that a certain tutorial was written in 2004 would definitely be a huge indication to a reader that it may be out of date.
List Version Numbers
If you are dealing with certain products or pieces of software then try to give version numbers. For instance, this tutorial:
"How to do Custom URL Routing in .NET"
Should actually be titled:
"How to do Custom URL Routing in .NET v4"
That version number makes a huge difference. In this particular example URL routing is very different in .NET v4 vs .NET v3.5. If you don't list a version number you might thoroughly confuse your readers. This goes hand in hand with putting a date on your tutorial, but I actually think this is even more important than the date. A date is an indirect hint that something might be out of date, but a version number is a direct indication that it is or isn't up to date. Not only that but some people may still be using an old version of whatever software you are discussing and your tutorial may still be of some use to them. Rather than updating your tutorials as the software changes, consider writing new ones for the new versions and listing the version numbers.
Tutorial writing can be a lot of fun. The feedback you get from your readers as you build up a reader-base is awesome and very helpful. In my opinion there is no better way to learn than to teach others. It forces you to understand a concept thoroughly or else look silly in front of those you are trying to teach. I encourage anyone that feels like writing a tutorial to go right ahead. Just keep some of these tips in mind when writing so that you give your readers an optimal experience.