[Tutorial] How to write a tutorial
#1

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!
  • [U]Calling[/I]
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.

(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.)
Reply
#2

Nice tutorial, I think it will reduce the amount of useless tutorials.

E: oh...Just read the credits and I think I have to say nice work Y_LESS... hehe.
And nice decision to repost it Abagial.
Reply
#3

Now we're gonna get spammed with Y_Less' threads. Great!
Reply
#4

Yeah but it's better than loosing all the knowledge we've gained from him over the years.
Reply
#5

Would be better if threads like this started with a disclaimer noting that this is an old tutorial made by Y_Less.
Reply
#6

I think it's good enough.
Reply
#7

Thank god for this repost.
Reply
#8

Quote:
Originally Posted by BleverCastard
View Post
Now we're gonna get spammed with Y_Less' threads. Great!
Do you really think those threads are spam or bad?
Reply
#9

Quote:
Originally Posted by Abagail
View Post
Yeah but it's better than loosing all the knowledge we've gained from him over the years.
You need a grammar lesson.

Quote:
Originally Posted by dominik523
View Post
Do you really think those threads are spam or bad?
He deleted them because he's a selfish prick. He chose to delete them, nobody needs to copy all of his threads again.
Reply
#10

Quote:
Originally Posted by BleverCastard
View Post
He deleted them because he's a selfish prick. He chose to delete them, nobody needs to copy all of his threads again.
Well, most of the people still use his includes so I think there should be some tutorials and info about them.
Reply
#11

A tutorial on how to make a tutorial.. Hmm.
Reply
#12

Quote:
Originally Posted by eXeDev
View Post
A tutorial on how to make a tutorial.. Hmm.
Yes. Check other tutorials. Most of the people just copy and paste their code and they explain nothing.
Reply
#13

Quote:
Originally Posted by dominik523
View Post
Well, most of the people still use his includes so I think there should be some tutorials and info about them.
Not being spammed by most users on this thread.
Reply
#14

He didn't delete it because it doesn't want it here anymore, but so that he would be more motivated to leave SA:MP so don't think he really cares that much if we re-post it.
Reply
#15

Quote:
Originally Posted by Abagail
View Post
He didn't delete it because it doesn't want it here anymore, but so that he would be more motivated to leave SA:MP so don't think he really cares that much if we re-post it.
He doesn't care, why would he? He can't care. It's against his own license to care what we do with his stuff.

@BleverCastard: How the fuck is it spam? Do you know what spam is? Each and every one of the reposted threads are 100% relevant and useful for everybody. Are you sure you want to talk about him being selfish? YOU are the one saying that the threads should not be brought back. YOU are the one saying that they are unneeded. You may have a bit of knowledge on the subjects, but what about EVERYBODY else! YOU are the selfish prick.
Reply
#16

Why isn't this thread stickied yet ?
Reply


Forum Jump:


Users browsing this thread: 1 Guest(s)