VERC: How to Write a Proper Tutorial Last edited 21 years ago2003-07-29 00:33:00 UTC

Table of Contents

• What is a tutorial? (Link: #Whatis)
• What should a tutorial include? (Link: #Whatinclude)
• What if I want to write a tutorial? (Link: #WhatifI)
1. Preparation (Link: #Preparation)
2. Target Audience (Link: #Audience)
3. Content (Link: #Content)
4. Formatting (Link: #Formatting)
• The Do's and Don'ts of Tutorial Writing (Link: #Dosdonts)
• Copy and Paste-proofing Your Tutorial (Link: #Cnp)
• Concluding Thoughts (Link: #End)

Additional References

• Writing Collective Articles (Link: index.php?doc=1044988999-42811100)

---

What is a tutorial?

A tutorial differs from a normal article or piece of writing in that it is a detailed list of instructions that one can follow to achieve a specific, predefined goal. A tutorial can also provide the reader with helpful images or content. In a sense, a tutorial is a set of instructions, yet a tutorial is unique in that it also should endeavor to teach the reader something about the subject matter at hand - hence the base word "tutor." An effective tutorial is not only one that guides the reader from start to finish without incident, but also provides any necessary material for successfully completing the tutorial. "Necessary material" can be anything from a snippet of source code to a full-blown application or third-party utility, however it is usually limited in scope to any resources that the reader is not expected to have prior to reading the tutorial.

What should a tutorial include?

The writing of a tutorial isn't a process that should be taken lightly. Unlike regular articles, your goal isn't to provide as much information as possible about a topic and let the reader make their own moves and decisions - the reader shouldn't be left to his or her own devices at all unless that is part of the instruction. Rather, you are there to provide the reader with specific goals and instructions they must follow. Along the way they should learn something related to the tutorial topic, but it is by no means an information piece where you should heavily elaborate on any topic, no matter how pertinent. Remember what purpose the tutorial is there to serve. It exists to guide the reader, and provide them with only the information necessary to complete the tutorial. This does include any information that would help the reader understand what they're doing, however all information should be directly related to tutorial content. As interesting as you think something might be, the reader is there to complete a specific objective. There is always room for an additional article if you feel the urge to expound. The difference between an article and a tutorial may be as thin as semantics, but both have their own flavor and purpose.

Never forget that a tutorial always has a definite starting and ending point. You should outline any necessary prerequisites for the tutorial, as well as let the reader know from the beginning what the end result will be. This "end result" should be something specific and tangible - if you only tell your reader something like, "You will know how to ..." or similar, then you don't have a tutorial. There is no guarantee the reader will know anything , but you can promise them they will have a working particle system or MP3 player (dependent on the accuracy and quality of the tutorial, of course; explained later). Aside from the beginning and end, there is also an extensive middle, which is comprised of the actual steps the reader must take. These steps should lead the reader along procedurally in a logical and cohesive manner. Depending on the subject matter of the tutorial, this could mean organizing your steps by source file, by map, by entity, by texture, etc. At the very least, the reader should have the easiest time you can allow for making the transition from step to step. Don't force them to go back and forth or allow them to become confused when a simple rearrangement of the tutorial content can ease their effort.

In the end, what constitutes appropriate information for a tutorial and what is simply extraneous content comes down to a large gray area, because by simply changing the objective of the tutorial you can appropriate anything ("Cooking and the Art of Client-side Messaging" for example). There is no right or wrong. Whatever you write could be considered apropos if you think it will help with what you stated you would accomplish. Simply take an active interest in the wants and needs of the reader. It's not advisable to bore them to death with information that doesn't help them understand or follow the tutorial. And I'm sure they wouldn't want to learn how to cook on the side.

What if I want to write a tutorial?

There will undoubtedly be a point in your Half-Life modding experience where you wish to pass on to others something you have learned to do and have already done yourself. Be it a complex mapping trick you stumbled upon by trial and error or the intricacies of coding a VGUI-controlled particle system, you will have the urge to write about your findings and explain to others exactly how you arrived at such results. If you heed the above advice, then you will simplify the process quite a bit by limiting the amount of information you have to organize, while at the same time being able to write an effective tutorial. The tutorial writing process can be broken down into several steps and considerations.

1. Preparation. How can you prepare for such a seemingly straightforward process? While this may not help after-the-fact, the best way to prepare for a tutorial is to contemplate writing one before you have finished your own personal discovery. While you are on your own way to a final result, begin to think in terms of how this can best be explained and presented to others. Is this source code a little sloppy, or do these entities have obscure names? How would I best describe what I'm doing at this point? Or what I have already done, or will do? How can I break down this process into discrete, logical steps? There are other benefits to thinking this way. Inherent in a tutorial is its ability to explain. Thinking in these terms might actual help you organize your own thoughts on the subject, and maybe even force you to consider something from a different light or point of view.

The best way to prepare is to recall your own experiences as you were going through the process on your own. Is there anything you would change? Any experiences you would have added or removed, or modified slightly? Always think in terms of how pleasant you can make the process for others, while still providing them with a good learning experience.

2. Target Audience. Before you begin writing, you have to establish who you are writing for . Everyone who has ever written a tutorial before knows that there is a very strong urge to cater to the lowest common denominator, and explain everything there is to explain in elaborate detail so that everyone can learn and understand, no matter what they know or don't know or what their skill level is in the subject. Truthfully, there is a good feeling associated with teaching others - otherwise no one would write tutorials - and inherent in this is the longing to teach as many people as possible. However, we all have to resign ourselves to the fact that we simply can't do such a thing and still keep our work in a concise tutorial form! Either you end up straying too much from the tutorial and turn it into an article, or you unintentionally leave out important steps and confuse readers. You, as a tutorial writer, know for whom the material is appropriate. You won't be teaching module hooking to any C++ novice anytime soon, and any attempt isn't worth your effort, because it's simply too advanced a topic. That's what you have to determine - how advanced your tutorial will be and what information you will presume the reader already knows. Use that to determine your target audience. What concepts should the reader already be familiar with that I simply can't cover here? And just how advanced are these topics? Once you've figured that out, stick with the assumptions. If readers should know how to use and employ a multi_manager or set up an origin brush for trains, then don't waste your time elaborating on these topics. At the same time, if you're writing your tutorial for beginning mappers, then you really should elaborate. Don't forget to keep on topic as well. Don't venture into the realm of multisource s unless it has something to do with your tutorial or intend to explain it. On the other hand, don't try to walk someone through the steps of creating an MP3 player if you're expecting them to have little to no programming experience. First, unless it's simply a C'n'P tutorial (explained later), your reader won't learn anything, and secondly, more advanced users who know all the basic concepts might simply become frustrated trying to sort through what they already know and what they might be able to learn.

Of course, it's only fair to inform your reader of the level of your tutorial beforehand. Ideally, explain to them what they should know, rather than just, "This is pretty advanced!" If you're lucky, they'll go out, get a proper education in these topics, and come back prepared. Think of it in terms of a band on the user skill-level spectrum. You want to stay within this band. Venture too far up, and your reader won't know what you're talking about, and will likely just get confused and frustrated. Meander too low, and you risk making your tutorial overwhelming due to the sheer amount of information and explanation it will require to be completed.

3. Content. One of the hardest things for a tutorial writer to master is the balance between content and explanation. In this context, content can be considered anything that is given to the user necessary to complete the tutorial, be it code snippets, example maps, or other resources that the reader doesn't have to create for themselves. This is especially pertinent for coding tutorials, because text is the editing medium itself. The key to writing an effective tutorial is finding a balance between how much you give to the reader, and how much you explain and subsequently expect them to figure out on their own. This doesn't mean you should ever leave the reader lost, as you should always be giving them instructions on what to do, but just how specific these instructions should be is up to the author. A common example of what happens when a tutorial loses balance is known as a Copy and Paste tutorial (C'n'P for short). This is when the reader is able to simply copy content directly from your tutorial and achieve the end result, bypassing any explanation whatsoever. While this doesn't immediately imply negligence on the part of the author, there are several measures that can be taken to lessen the likelihood of your tutorial being C'n'P-able (explained below). On the other end of the spectrum, you can have tutorials that have way too much explanation, but not enough content to give the reader solid direction. How does the reader know that they're following the tutorial correctly if they have nothing to compare it to? They just have to wait until the end and hope everything works as it should? Or maybe this is how you want your tutorial to be written. The balance between content and explanation is something that needs to be worked out by the author, and while there is no hard and fast rule, it's usually best to have an equal amount of each.

4. Formatting. Formatting can make or break the effectiveness of your tutorial. Something too complicated has the potential to intimidate and frustrate readers. The most straightforward approach is the ever-popular 1-2-3 format, where each step in clearly and distinctly separated and numbered. Each step includes instructions, content/material, and and explanation. Anything else you want to add is fine, and you can fit it in anywhere, but it's usually best to keep the instructions and content nearby, so the reader always knows which instructions go with what content. Images are always a big help if you feel that textual instructions will be inadequate. This is more often the case with mapping tutorials, which take place in a GUI environment.

When working in a medium as colorful and dynamic as the internet, you have many options when it comes to the presentation of your tutorial. Usually you'll want to keep your tutorial's presentation simple and straightforward so it isn't intimidating or hard to follow. If you follow the above 1-2-3 approach, then a quick link section at the top of your tutorial that allows readers to jump to specific steps might be a welcome addition. Separate colors for different types of text, like code, is also a smart move. However, don't choose bright or annoying colors like yellow. Make sure your color scheme is pleasant to the eye. And regarding source code, make sure that it is properly formatted and indented so that it is easily readable - if it isn't, then you risk losing your reader. There isn't much more to be said about formatting, as it is highly dependent on the tutorial itself as well as the author's personal preference. Yet above all else, keep the reader in mind as the top priority.

The Do's and Don'ts of Tutorial Writing

The following is a list of things you should either do or not do when writing a tutorial. I've tried to list them in their relative orders of importance, however you may think some are more important than others higher up. Whatever the case, these are rules you should attempt to adhere to.

• Do proofread your tutorial! This includes going through and making sure all grammar and spelling is correct and that your explanations are clear and coherent. I can't tell you how many tutorials I've read where I couldn't even understand what the author wanted the reader to do. If you really need to, send your tutorial to a friend or acquaintance that can read your tutorial for you and tell you if there are problems. Ideally, you should pretend you are reading your tutorial for the first time, and see if you can understand what you're supposed to do. While it's hard to strip yourself of such knowledge, you must try. At any rate, heed the following warning. I've seen tutorials that were either technically inaccurate or incomplete ! As far as tutorial writing is concerned (or any other sort of nonfiction writing for that matter), that is unacceptable ! Code snippets should not contain obvious syntax errors. Mapping tutorials should not outline a process that is impossible to complete, or provide false information about entities. Any tutorial should be able to guide the reader from start to finish without incident, as mentioned in the beginning. The reader should never have to guess as to what they should do next. They should at the very least have a reasonable idea. If you don't proofread, then you aren't a very good writer. Sorry, that's what it comes down to. Technical accuracy and completeness is key, so if you have to chose between erring there and bad English and/or explanations, choose the lesser of the two evils and go with something that can still provide the reader the something useful.

• Do follow your own tutorial! This may seem like a redundant step, but it is the only way you can really make sure your tutorial works as intended. Put yourself in the shoes of your reader. Forget what you know about the topic. Whatever the subject, start with a clean slate. If it's a mapping tutorial, then start with a blank map. If it's a coding tutorial, start with a clean SDK. This may seem like overkill, however it is almost a 99% failsafe method of testing your tutorial. Let's say you forgot to add something to your tutorial that's necessary for it to work properly. If you don't start with a clean slate, then it might work merely because of that change that was made you forgot to mention. Then, when someone else tries to follow your tutorial, it doesn't work for them because of that modification you made but was never mentioned in the tutorial. Save your readers the heartbreak and make sure it works.

• Do try to keep your tutorials up-to-date! As time goes on, things change. Code bases can change, entity behavior can change, mapping environments and compile tools can change. If you can, try to keep your tutorials up-to-date so that new readers will still be able to follow them. This might not be very easy, as often a tutorial writer will submit a work to many different sites over which they have no control, and then forget about it entirely, until they get that confused e-mail from Harold Headcrab saying that he can't find the option you told him to set, because it doesn't exist anymore! You don't need to write an entirely new one. Simply make changes or notes throughout indicating what has changed.

• Don't plagiarize! Oh yes, the obligatory plagiarism paragraph. I'll make this short, because I really can't elaborate beyond the point that you simply don't take other people's work and slap your name on it, unless you ask their permission and give them credit. Please, this will save you lots of trouble in the long run. People who plagiarize lose all credence in their respective community, and it is almost impossible for them to regain that trust again without building up an entirely new identity from the ground up. It will ruin you, because someone always finds out. Just don't do it. You will be caught.

• Don't use tutorials as a replacement for a proper education! As good as you may think you are, you aren't going to outdo a seasoned Microsoft author when it comes to teaching someone C++ or the Win32 API. And you definitely aren't a replacement for personal experience and trial and error. So save yourself a hassle and try not to explain such broad topics in one big tutorial. This relates to the point I made before regarding how much information you put into your tutorial. You can't explain everything there is all at once, so don't stress yourself out. Break it down, or better yet, turn it into a formal article that isn't as strictly structured as a tutorial. Remember that a tutorial always provides the user with something tangible, whereas an article doesn't have that restriction.

Copy and Paste-proofing Your Tutorial

This isn't a section you have to read to understand good tutorial writing. Rather, it's here for the people who really and truly don't want their code to just be taken, regardless of whether they're given credit or not. For starters, there is no 100% foolproof method of making your tutorial impossible to copy and paste. An effective tutorial includes the content that makes it possible to begin with - Catch 22 indeed. But what you can do is make it difficult to accomplish. Take the following excerpt from a fictional tutorial:

Add this code to line 234 in foobar.cpp:

for(int i = 0; i < 255; ++i){ cout << i << endl;}
The previous code loops i from 0 to 255 and prints each value on a new line.
So far so good. Instructions, code, and explanation and easily to identify (even if it wasn't the classiest choice of colors). However, all a reader has to do is locate red and green blocks, and follow the instructions for the code, completely ignoring the explanation part that gives the tutorial writing process its redeeming value (for me at least). While it may appear as though there is no alternative, examine below the same excerpt in a slightly different format and presentation:

for(int i = 0; i < 255; ++i){ cout << i << endl;}
The previous code loops i from 0 to 255 and prints each value on a new line. It should be added to foobar.cpp on line 234 .
Maybe not as straightforward, but still easy enough to follow for someone interested in actually reading the tutorial and not ripping your code. You interweave the instructions with the explanation, making it harder to locate on its own.

However this begs the question - Are there any side effects of doing this? Well, yes unfortunately. The most obvious one is that it makes your tutorial harder to reference later on. Maybe someone who has followed the tutorial once already needs to quickly locate a specific instruction that they might have misread of made a mistake following. It will be harder for them to locate instructions unless they are familiar with the layout of the tutorial. To combat this, you could always implement the quick link system suggested above, but sometimes you might not always have that option. It's all up to you.

Concluding Thoughts

I applaud you for making it this far, because this really was a monster of an article. However after my several years of experience in the Half-Life editing community and with all the tutorials I've read (and a few that I've written myself), I decided it was about time I sat down and compiled everything I knew about what makes a good and bad tutorial into a single article. I by no means consider myself a connoisseur in tutorial writing, and neither should anyone take this as the definitive guide to writing a tutorial, but these are some of my thoughts on the subject, and hopefully I've raised a few issues that need to be considered more closely as well. Highly open to interpretation and debate? Yes it is, yet at least it's something to work from and expand on.

If you are looking for some more information on writing effectively in general (specifically Collective articles though), then I encourage you to read this (Link: index.php?doc=1044988999-42811100) article. It will help you get started as well as reinforce a few of the points I made here.