After reading this tutorial, you should be comfortable with designing, creating, and writing a comprehensive, intelligent tutorial that will not only impart your knowledge to others, but allow you to do so in a way that will be useful to anyone who requires the training your tutorial offers. You will understand the steps required to make your tutorial easily followed and your key points easily understood. In addition, you will better understand what is required to make your tutorial useful to your prospective readers in conjunction with all other tutorials and resources he might be using.

PREREQUISITES: As long as you can read and understand English, you should have no difficulties with this tutorial.

You can, optionally, print this tutorial out rather than read it from the computer.

When considering writing a tutorial, do not simply jump into the process without first thinking it through. You have the knowledge; now, you wish to share it with others. If you are going to take the time to write the tutorial, you might as well write it correctly. Grab that cup of coffee or soda, sit down with a pen and paper or open up a word processor on your computer. Make your important notes about the tutorial you intend to write as you read this tutorial.

1. SUBJECT COVERED WITH THE TUTORIAL. This can often be described in the title of your tutorial. The title of A Tutorial on Writing Tutorials For Torque Developers is self-descriptive. More is not necessary.

2. GOAL OF THE TUTORIAL. Make certain that the reader understands the purpose of the tutorial and what he expects to learn as he goes through the steps of the tutorial.

3. TABLE OF CONTENTS. If the tutorial is small, a table of contents is not necessary. If it is too large to see in more than a couple screens worth of text, consider adding a table of contents or, better, a linking table of contents. This table of contents should be the first thing listed after the #2. Goal of the Tutorial sections of the tutorial.

4. PREREQUISITES. Make a list of what the reader should know before beginning the tutorial. Wherever possible, provide the reader with links to prior, supportive tutorials and useful resources. This section should appear directly after the Table of Contents.

5. TERMS AND ACRONYMS. Next, a glossary of terms should be listed. Define all terms that might be construed to be unusual or technical that will be used in the tutorial. This creates a small glossary for the reader to refer to while reading your tutorial. If the glossary is of significant size, simply note that the glossary exists at the end of the tutorial. AN ALTERNATIVE TECHNIQUE: Though, not the best method, define the term or acronym the first time it is used. BEST TECHNIQUE: Provide the glossary AND define the term the first time it is used.

6. LAYING OUT THE TUTORIAL - SUBJECT MATTER. Jot down the ideas you wish to cover with your tutorial. Consider each aspect carefully then add any concepts required to fill in the gaps. Make certain that you cover every aspect required to perform the expected, tutorial task.

EXAMPLE: If you want a reader to place a file into the project, make certain that he understands not only exactly where to place the file but where he must exec the file, if that is necessary, as well. A note to make certain that added files are also included in a project through IDE when necessary would be prudent as well. Never assume anything.

Keep in mind that for a reader to fully comprehend your tutorial, each step must be carefully explained. Don't assume that the reader knows how and where to exec a file, for example. Take the time to make certain he performs the task you expect him to in order to successfully move on to the next step of the tutorial. Even when actions seem obvious to you, they are not obvious to the newbie. He might still be wrestling with the most basic components of the subject matter.

7. LAYING OUT THE TUTORIAL - FORMAT. You will notice that, in this tutorial, I have used a basic numbered format approach, separating each section with a space. I am not suggesting that this is the only approach, but SOME approach of step separation must be implemented. Otherwise, your work will run together. It can, and has, occurred that code has run into description. A reader could easily grab two sections of code and include it into a paste function. The result would include frustration and lost time. Use special formats for quotes and code whenever possible. These techniques can be invaluable to the readability of your tutorial.

8. THINGS TO KEEP IN MIND AS YOU WRITE YOUR TUTORIAL- VISUALS. Give a visual, wherever possible, of how the initial or final result should appear. Visuals increase the learning capability by 200%. The visual could simply be examples similar to what is being used in this tutorial (See step #6 and step #12). For those readers trying to understand and grasp the concepts of a tutorial, visuals can be very important.

9. THINGS TO KEEP IN MIND AS YOU WRITE YOUR TUTORIAL- ALTERNATE METHODS. If you are going to include an alternate method, set it apart from the rest of the tutorial, using bold or italic type and with a CAPS header that indicates that it is an alternative. This lets the reader visually understand that the alternate method is separate from the main tutorial and will then be easily understood.

10. THINGS TO KEEP IN MIND AS YOU WRITE YOUR TUTORIAL- REDUNDANCIES. As with Alternate Methods, the same holds true if you are going to be redundant in an explanation. Telling a reader how to do something twice may infer to the reader that he should do the task twice.

11. THINGS TO KEEP IN MIND AS YOU WRITE YOUR TUTORIAL - NEVER ASSUME. I can not stress this enough: NEVER ASSUME! The fastest way to lose your reader is to assume he knows something. If a reader is required to have prior knowledge of some resource before using the tutorial, make certain that requirement prefaces the main body of the tutorial in #4 Prerequisites.

12. THINGS TO KEEP IN MIND AS YOU WRITE YOUR TUTORIAL - NATURAL MOTION OF THE TUTORIAL. Before doing any actual writing of the tutorial, take a good look at the subject matter you intend to cover. Rearrange your notes into a smooth 'story' so that the reader moves from one aspect of the tutorial's concept to the next in a natural motion.

EXAMPLE: Notice that this tutorial provides the reader with a top down sense of the tutorial. We begin at the top of the tutorial with those things that are expected at the top of the tutorial: Subject/Title, Goal, Table of Contents, Prerequisites, Terms and Acronyms. We then move on to the intuitive portion of the tutorial that will help develop the tutorial itself, including how to lay the tutorial out and things to keep in mind AS you write the tutorial. Next, the tutorial addresses the actual writing of the tutorial in logical fashion: Where to Begin, The Body of the Tutorial, Ending the Tutorial, and Summarization Once the tutorial is complete, you are then instructed what to do with it: Edit it and include resources where the reader can continue his study on the subject. And finally, what to do once the tutorial is complete, addressing maintenance, and additions.

13. WHERE TO BEGIN. Set the reader up properly before he begins the actual body of the tutorial. Include a detailed explanation as to where the reader should acquire his files, data, etc, such as exactly what directory. Do not assume that the student knows what you are talking about unless your intent is to frustrate your readers at the outset. Not making certain of this initial aspect is akin to placing your race horse backwards at the starting gate.

14. THE BODY OF THE TUTORIAL. Ironically, this is now the easiest part of the tutorial. You have plotted all your points you wish to cover, considered how to make your 'story' flow, and have a feeling for your tutorial. Now, simply flesh out your points of the tutorial, add your code snippets, add your examples, and any other aspects you deem necessary to make the tutorial a workable project. The body may be rough at this point, but it is complete.

15. ENDING THE TUTORIAL. Make certain that the reader understands what his code should do at this point, how it should perform and make suggestions as to how to correct any possible 'obvious' or common errors. Save troubleshooting for step #20 Additions to the Original Tutorial.

16. SUMMARIZING. Once the reader has completed your tutorial, make certain he understands what he has accomplished. Let him know that he is now armed with knowledge that will allow him to move on to the 'next step' whatever that might be. "Good job' is not a bad thing to remember to tell the person who has struggled (or not) through your tutorial and completed it.

17. EDIT. EDIT. EDIT. CONTENT. Now, to polishing the tutorial. Make certain that your tutorial is correct in content. If you think your reader is frustrated by simply misunderstanding something that is poorly written, think how frustrated he or she will be after following your tutorial three or four times and failing because you wrote "games.cs" instead of "game.cs."

18. EDIT. EDIT. EDIT. GRAMMAR. No one expects your tutorial to be professionally edited, but the reader does expect to be able to understand the instructions easily. After all, the reader has the concepts to struggle with, already. He does not need to battle concept and interpretation simultaneously. There is no point in sharing your knowledge if you cannot communicate. If you have knowledge you wish to share but cannot write a grocery list to save your life, write it to the best of your ability then email it to a friend to edit for you. Re-read the edited version to make certain it communicates what you intended, make corrections then repeat the process (that is, send it off for a new edit and re-read it again). After that process then submit it as a post. Remember, you are not only sharing your knowledge, but putting people in a position to waste hours and days of their lives if you have made errors that could have been prevented. Think of it this way: If you cause an error that requires only one hour of lost time and twenty people make that error, that's twenty hours of lost time. In this industry, those hours can add up rather quickly! In addition, a tutorial that is written with some attention to detail and professionalism is taken much more seriously than the half-baked brother of the same tutorial.

19. SEND YOUR READER TO THE NEXT STEP. Okay, so the reader has finished your tutorial. Let him know what tutorials might exist in the same series or where the reader might go to expand his knowledge even further (if it applies). Adding links to the tutorial, whenever possible, can be an invaluable step to the reader. You have taken him this far, push him farther along the road of knowledge.

20. ADDITIONS TO THE ORIGINAL TUTORIAL. When adding a section to the body of the tutorial or tutorial file, say, from a posted suggestion, make it very clear in the suggester's post (if possible) and in the original tutorial preface what additions have been made. Also note when they were made and by whom they were made (if you wish to give credit where credit is due). This is also a great place for adding a troubleshooting section.

21. MAINTENANCE. There are a few different places maintenance can be performed: A) Continued maintenance of your tutorial can include the correction of typos, spelling and grammatical errors, formatting errors and so on. B) Content errors can crop up at any time. Something considered standard might turn out to be dependent on operating systems or in special environments. Be prepared to keep your tutorial updated with new information. C) Troubleshooting can be very useful to someone having difficulty with your tutorial. The problem may not have been anything you had considered, but help the reader out as much as possible. As mentioned in step #20, the Additions to the Original Tutorial section, that would be a great place to maintain a troubleshooting guide. A great deal of the troubleshooting will probably come from other users. This is helpful in creating a comprehensive troubleshooting guide.

If you have used this tutorial to write your tutorial, well done. You have been given the tools to write a better tutorial and undoubtedly, you can see the difference. Writing a fluid tutorial with definitive direction and in a comprehensive format will provide the community with a useful resource that people will refer to again and again. You are now capable of not only gaining the respect of your fellow developers but of professionals of all walks of life who happen onto your work, however small it might be. After reading your tutorial, the reader will be left with a sense of competency which, as a developer, you will require. You now have the opportunity and one more tool to help ensure your own future.

No one can force you to use this tutorial's template and no one can force you to communicate well. However, you will find that the better you communicate with people the better more people will communicate in return. You are putting a great deal of effort into the content of your tutorials. You might as well make certain that you package your intelligence in a format that people can comprehend and use. Armed with this knowledge, you can prepare and write tutorials knowing that your work will be well-received and considered professional. It doesn't take a great deal of time to be professional when writing a tutorial, just the understanding of 'how' to perform to be considered professional. You now know 'how.' The rest is up to you.

Print this post off and use the following as a checklist when writing your tutorial.

  [  ]   1. SUBJECT COVERED WITH THIS TUTORIAL
  [  ]   2. GOAL OF THIS TUTORIAL. 
  [  ]   3. TABLE OF CONTENTS.
  [  ]   4. PREREQUISITES. 
  [  ]   5. TERMS AND ACRONYMS.
  [  ]   6. LAYING OUT THE TUTORIAL - SUBJECT MATTER.
  [  ]   7. LAYING OUT THE TUTORIAL - FORMAT.
            [  ]   8. THINGS TO KEEP IN MIND AS YOU WRITE YOUR TUTORIAL- VISUALS.
            [  ]   9. THINGS TO KEEP IN MIND AS YOU WRITE YOUR TUTORIAL- ALTERNATE METHODS.
            [  ] 10. THINGS TO KEEP IN MIND AS YOU WRITE YOUR TUTORIAL- REDUNDANCIES.
            [  ] 11. THINGS TO KEEP IN MIND AS YOU WRITE YOUR TUTORIAL - NEVER ASSUME.
            [  ] 12. THINGS TO KEEP IN MIND AS YOU WRITE YOUR TUTORIAL - NATURAL MOTION OF THE TUTORIAL.
  [  ] 13. WHERE TO BEGIN.
  [  ] 14. THE BODY OF THE TUTORIAL.
  [  ] 15. ENDING THE TUTORIAL.
  [  ] 16. SUMMARIZING.
  [  ] 17. EDIT. EDIT. EDIT. CONTENT.
  [  ] 18. EDIT. EDIT. EDIT. GRAMMAR.
  [  ] 19. SEND YOUR READER TO THE NEXT STEP.

Copyright 2005 K. Silver