World of Scripters!

SA-MP Server => Tutorials => Topic started by: Y_Less on July 22, 2012, 05:36:50 pm


Title: How To Create a Tutorial
Post by: Y_Less on July 22, 2012, 05:36:50 pm
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

    Authority


If you write a tutorial people will assume you know what you're talking about - why write a whole tutorial on something you don't know about? If they're doing something a different way they very rarely check which way is better, they simply assume the tutorial way is because it's in a tutorial!

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 thread people will question things, if you put a solution to a problem forward other people may think they have a better solution and put forward theirs, it doesn't matter if it is or not - the discussion is there.

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


There is a big problem in this community of bad information propagation. I'll take two common examples - 256 and strtok. In the early days of SA:MP scripting these were common and accepted methods, they got the job done and people didn't know any better. As time went on people developed better methods (namely dcmd/sscanf, smaller arrays etc) so the old methods should have been forgotten right? Wrong!

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!

    Calling


For the reasons above I make an effort to read all tutorials posted and if I find something I know to be wrong I'll call them on it. If you post a topic you are telling the world you know something, if someone else can show that you DON'T know it then you shouldn't have posted the topic in the first place. Very few people call people on information in tutorials and it's a shame, I honestly wish people would do it to mine!

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.
__________________
If your topic says "REP+", I ignore it.


Title: Re: How To Create a Tutourial
Post by: Lordz on July 22, 2012, 05:50:29 pm
Hmm,nice posting.
Title: Re: How To Create a Tutourial
Post by: SUDARSHAN on July 24, 2012, 10:33:15 am
donot got anything
Title: Re: How To Create a Tutorial
Post by: Kalroz on July 24, 2012, 06:25:45 pm
I hate lectures from teachers,especially for history.
This post is like this,i dont think there should be a rule like this for posting tutorials.
No this,no then...
Wth?
Begginers aint give good tutorials without 'this' 'then' etc.
Title: Re: How To Create a Tutorial
Post by: YoUnG_Ca$h on July 28, 2012, 03:30:34 pm
I hate lectures from teachers,especially for history.
This post is like this,i dont think there should be a rule like this for posting tutorials.
No this,no then...
Wth?
Begginers aint give good tutorials without 'this' 'then' etc.
Agreed.