15.04.2015, 02:15
How to write a tutorial
Introduction
Time and time again I see people writing bad tutorials and bad how-tos on this forum, so I'm writing this one as a guide to those people.
Please note that I'm not trying to discourage people from writing tutorials, just trying to explain how to go about doing it.
Problems
For that reason if you write a tutorial you are effectively saying you have knowledge on a subject and are qualified to write about it.
In a tutorial people will assume that your way is right, you don't make topics to teach something that's wrong (well, people do, but that's what I'm trying to stop). Very rarely will people actually question information in a tutorial.
Because people still used the old methods in their modes (updating is a lot of work so this may be fair enough) they continued to teach new people them, who then themselves taught people them. If you know you're not using the most up-to-date way of doing something WHY POST? Either explain the better way, regardless of whether or not you use it, or just don't post in the first place!
Research
This seems to be sorely lacking when people write tutorials - if you are going to tell someone else how to do something the FIRST thing you should ask yourself is if YOU are doing it as well as you can? Just because you've been doing something for years and it's never failed you doesn't make it good.
If you're posting a function - review it, review the literature on it, see if there are alternate implementations about. If you have to get multiple versions and time them, see which uses the most time or the most resources etc. It may mean you have to alter your tutorial but so what? It means other people are learning a better method, which is what the point of writing a tutorial is in the first place.
Explanations
Tutorials which simply say "do this, then that, then the other and you're done" are stupid. Some people may just want step-by-step instructions but other people want to know WHY you're doing that. Write the step-by-step guide, put it at the top, but then add explanations further down. Any scripter that's likely to ever be any good will be the sort who finds out WHY you do things, not just WHAT you do.
Also, if you explain why something is done they can improve your method or decide better when to use it and when to not.
Presentation
This is quite important, however it's not my strong suit so I won't write too much.
Just make sure it's neat, and in small sections if possible. I realise this is a very text-based tutorial so is not the best example for this, but try to break up large chunks of text with a code block or the like. People don't like large chunks of text.
Also WHERE to post it is important. I would 99.9% of the time say the wiki but it can depend. And if it's on a single mode or include put it in that thing's topic - you know the rules on topics about releases!
An introduction and conclusion also tend to be good.
Misinformation
I just want to stress this point again - make sure what you post is in line with current practices. If you have a command use dcmd (or similar), if you need an array work out how big it should be etc.
Also make sure that what you're saying is as good as it gets, it may well be improved upon later but just make sure it's not been improved upon in the past.
Conclusion
Research your article and remember that if you post bad information I, and hopefully others now, will call you on it and make you look like a fool.
(Originally posted by Y_Less: I did not write any part of this tutorial, however as Y_Less has left SA-MP I have re-posted this as it is very useful to people new to the SA-MP forums, and people who generally want to write great tutorials. Cheers.)
Introduction
Time and time again I see people writing bad tutorials and bad how-tos on this forum, so I'm writing this one as a guide to those people.
Please note that I'm not trying to discourage people from writing tutorials, just trying to explain how to go about doing it.
Problems
- Authority
For that reason if you write a tutorial you are effectively saying you have knowledge on a subject and are qualified to write about it.
- Not a thread
In a tutorial people will assume that your way is right, you don't make topics to teach something that's wrong (well, people do, but that's what I'm trying to stop). Very rarely will people actually question information in a tutorial.
- Dating
Because people still used the old methods in their modes (updating is a lot of work so this may be fair enough) they continued to teach new people them, who then themselves taught people them. If you know you're not using the most up-to-date way of doing something WHY POST? Either explain the better way, regardless of whether or not you use it, or just don't post in the first place!
- [U]Calling[/I]
Research
This seems to be sorely lacking when people write tutorials - if you are going to tell someone else how to do something the FIRST thing you should ask yourself is if YOU are doing it as well as you can? Just because you've been doing something for years and it's never failed you doesn't make it good.
If you're posting a function - review it, review the literature on it, see if there are alternate implementations about. If you have to get multiple versions and time them, see which uses the most time or the most resources etc. It may mean you have to alter your tutorial but so what? It means other people are learning a better method, which is what the point of writing a tutorial is in the first place.
Explanations
Tutorials which simply say "do this, then that, then the other and you're done" are stupid. Some people may just want step-by-step instructions but other people want to know WHY you're doing that. Write the step-by-step guide, put it at the top, but then add explanations further down. Any scripter that's likely to ever be any good will be the sort who finds out WHY you do things, not just WHAT you do.
Also, if you explain why something is done they can improve your method or decide better when to use it and when to not.
Presentation
This is quite important, however it's not my strong suit so I won't write too much.
Just make sure it's neat, and in small sections if possible. I realise this is a very text-based tutorial so is not the best example for this, but try to break up large chunks of text with a code block or the like. People don't like large chunks of text.
Also WHERE to post it is important. I would 99.9% of the time say the wiki but it can depend. And if it's on a single mode or include put it in that thing's topic - you know the rules on topics about releases!
An introduction and conclusion also tend to be good.
Misinformation
I just want to stress this point again - make sure what you post is in line with current practices. If you have a command use dcmd (or similar), if you need an array work out how big it should be etc.
Also make sure that what you're saying is as good as it gets, it may well be improved upon later but just make sure it's not been improved upon in the past.
Conclusion
Research your article and remember that if you post bad information I, and hopefully others now, will call you on it and make you look like a fool.
(Originally posted by Y_Less: I did not write any part of this tutorial, however as Y_Less has left SA-MP I have re-posted this as it is very useful to people new to the SA-MP forums, and people who generally want to write great tutorials. Cheers.)