This might annoy some people, but it has to be said:
Noobs should NOT write tutorials!
Far too many inexperienced users on here are writing what they think are tutorials which are full of incorrect information. Other noobs are reading them and thinking that what they have read is correct when it is not.
Tutorials need to be done properly or they do more harm than good and some, (definitely not all) leave a lot to be desired.
Tutorials are read by newcomers who soak up information like an empty sponge. So, if your tutorial contains bad information, they will assume that it's correct - after all, the tutorial author has experience and knows what he/she is talking about right?
Obviously not always...
Know Your Subject!
You shouldn't attempt writing a tutorial if you don't know the subject inside out. What's the point if when you've finished, other more experienced coders have to correct your mistakes or if when someone asks you how to modify it to do something else and you don't have a clue how?
I've seen this happen in so-called tutorials in the past.
Writing Style
You either have it or you don't. Your tutorial should be smooth flowing and easy to read as well as informative. Plan it so that you don't mention something before introducing it later on. Try to cover things sequentially in sections in the order they are needed to complete the task.
Try to create a rapport with your reader - suggesting that 'we' are going to do something next - giving the reader the impression that you are only talking to them and that they have your undivided attention.
What Is A Tutorial
Reading some of the tutorials on here, it's apparent that the definition of what a tutorial should be isn't clear to everyone.
A tutorial should explain in detail how to do a given task, covering how it's done and whenever possible
why it's done.
Simply putting lots of lines of code without explaining how the commands work or why you used them is no more helpful that copying and pasting code from the Code Snippets board.
You could even point out the pitfalls for beginners and reasons why doing it the way you did it is better than another way.
What you should avoid is stating the obvious:
GH# = Get Ground Height(1,Px,Pz)+2.0
This gets the ground height.
Well duh! Tell me something I don't know. Like how?
What's that # thing? What's the 1 for? What's Px and Pz?
You see what I'm getting at? Simply saying it get's the ground height is not acceptable in a tutorial for beginners. You can guess as much from the function name 'Get Ground Height'.
Indentation:
Another thing a seasoned programmer does is indent code. If the listings in your tutorial aren't indented, then don't expect anyone to read your tutorial. I certainly wouldn't!
Indented code is easier on the eye and a lot easier to read.
This however cannot be achieved on this forum as all extraneous whitespace is removed from your text when it is posted.
To get around this, use the code button at the top of the Edit Forum Messsage panel. Simply paste your indented code in, highlight it with the mouse and click on the button. Your code will appear like this:
Line Not Indented
Line Indented
Back To Not Indented Again
Layout your program listings correctly. A main program loop with 200 lines of code and no procedures is untidy, hard to read and shows lack of programming experience.
Keep your main loops as short and uncluttered as possible.
Move code into procedures or functions which do specific tasks repeatedly. This leaves your main loop consisting primarily of lots of Gosubs/function calls.
GOTO:
This is a real no-no! You should never, ever, ever use the Goto command in a tutorial as it promotes unstructured programming to newcomers.
Goto is a legacy command and is a throwback to the days when we used programming languages which didn't have procedures and functions. It's only left in there for compatibility reasons and in my opinion should have been removed years ago!
Anyone with programming experience can easily write programs without using Goto. If you don't have the knowledge to avoid using Goto then you shouldn't be writing tutorials!
Spelling:
There's nothing worse than a tutorial full of typos. If you can't spell, for goodness sake use a spellchecker or dictionary before you post.
Target Your Audience:
Tell the reader early on, what experience level your tutorial is aimed at. Let them know as soon as possible what you expect them to already know.
Is your tutorial for complete beginners or intermediate where you expect them to already know what arrays are and how they work.
If possible, give them links to other tutorials which explain topics in detail if they aren't sure - so they can read them and then come back and carry on reading your tutorial.
Conclusions:
All this takes lots of time and hard work - definitely not for the faint-hearted. But if you are going to do a tutorial, make sure that it really
is a tutorial and both informs and educates the reader.
Good luck!
TDK_Man
