Writing tutorials

As you guys may know, I've been working on an ASM tutorial the past few months (accumulated amount of time spent on tutorial is probably 2 whole weeks or so). I've never actually studied on HOW to write tutorials. I just 'followed' my instincts pretty much. Of course, I also keep running into obstacles. I thought I should share my method of writing tutorials, along with the obstacles.

From my point of view, there are two kinds of tutorial: one which teaches you to use something (e.g. how to insert blocks tutorial), and how to do something (e.g. ASM tutorial). The former remains the same (the overworld editor is not dynamic), as for the latter, you'll have to puzzle the pieces together (you can do a shitload of things with ASM - it's probably like cooking). I'm mainly focusing on the latter type of tutorials.

My main point of view when writing such tutorials is to NOT make people mimic you, but rather explain to them what exactly is going on, and how you can 'reproduce' the effects pretty much. If you tell people that "LDA #$01 STA $19" will store "01" into "7E0019", how will they know that the accumulator will be loaded with 1 in the process?

I actually learned ASM that way thanks to tutorials - "LDA and STA will magically store numbers into a RAM address!". I never knew about the accumulator. Then I found a routine - the block shatter effect which could either be plain brown or rainbow-colored. It said "load 1 into the accumulator to make the shatter rainbow-ish". I didn't know how to do that, and I asked smkdan for help. It was a very embarrassing moment once I realized how ASM truly worked like. smkdan probably had to laugh while helping me :D

Another thing I try to do is to go from the most important thing to the least important thing. I mean, lets take ASM again for example. It's important to know opcodes and all, but what's more important: ASM or counting in hex? If you don't know hex, you might as well forget learning ASM. That's why I'd explain hex first, then ASM.

I will also try to supply as many examples as possible. They demonstrate how everything is supposed to be, and how you're REALLY supposed to do things.

Next up: An image tells more than a thousand words (it was worded that way, right?). The next version of my ASM tutorial will feature this. An example is the bookshelf behaviour of the stack. I actually illustrated that because I found it difficult to explain. I added an explanation regardless though because you know, placing an image without any explanation isn't really useful.

Finally, I try to not overcomplicate things, and try not to involve the other chapters in the current chapter, otherwise it'll be almost the same as 'spaghetticode'. When I explain LDA and STA, I'm not suddenly going to involve conditional storing which involves processor flags or something - I'll divide them into multiple chapters. This is actually my main struggle in writing my ASM tutorial, because nearly everything is linked together in such a strange way. I might have to reorganize my chapters D:

Also, don't make mistakes in your tutorial (common sense but I should mention it regardless).

As for the other type of tutorials, I haven't really looked into that one, so I can't say much about it.

And again, this is from my 'instincts', everything made up by me, by teaching myself. There are bound to be better tutorial writing methods out there!