   Tutorials: Helpful/Harmful.
  Recently, I've been working on writing something up to be posted somewhere around here [and/or perhaps other places], and as I've been working on it, I've been reading other tutorials/articles/etc on various sites for inspiration [seeing as I'm a rather poor writer, and I want to see how others construct these sorts of informative articles so that I may better construct my own].I don't intend to name specific authors, as my goal is not to start fights, but I am curious of the opinions that rest of you have about tutorials and instructional articles.  The more of them I read, the more I'm thinking that they are actually in many cases [though of course not all cases] rather harmful to the process of learning something new.  Of specific concern are the source-code heavy tutorials, even many that are almost entirely source code with a sprinkling of comments [comments that the more of them I'm reading, the more I'm remembering from the work of others seeing these exact comments before....].  I see an awful lot of "This is how you do THIS" tutorials, instead of "This is 'A' way to do THIS".  The more I read, the more I'm wondering if I'd just be contributing to 'the problem' by releasing my work, and how can I avoid these pitfalls.So I ask you.... What is your opinion of tutorials in general, or specific kinds of tutorials, and why do you hold these opinions and make the distinctions you make?   
  I really think it depends upon the person.  I personally learn better by seeing something, and then adapting it to my needs.  When I see books or people explaining things, it's just 'meh'.  Other people learn differently.The one area you have to be careful about tutorials is when people have wrong information.  This happens a lot.  Or they lead people into bad habits.  On the other hand, without a little helpful nudging, people would most likely end up going down the wrong path anyways.   ;  It really does depend on the content of the article and whether or not that content is accurate. A lot of people have their own opinions, and opinionated articles are the worst of the worst because you're not teaching general concepts, you're teaching what you think is the right way to do things. I'll even use myself as an example. I think my Art of Code Documentation article is very, very opinionated. Mostly it was driven from my personal frustration with working with people who failed to comment properly or read comments to understand want something does. In fact I want to sit down at some point and totally re-write it.However this is why I always encourage people to read new articles on the site and comment them in the forum thread that each article spawns. This way anything wrong with the article can be expressed and addressed by me, the author or the rest of the community.   ;  In my opinion, 90% of game development tutorials are crap. They don't aid you in understanding the concepts behind code; on the contrary, they encourage a cookbook approach. They cast game development as a series of discrete skills to have (as though every professional game developer spends his days writing BSP loaders and implementing shadow mapping) at the expense of more generally useful CS theory.   ;Quote:Original post by GaiidenI'll even use myself as an example. I think my Art of Code Documentation article is very, very opinionated.Strangely enough, I went to go read that, and found myself disagreeing with almost everything :)   ;Quote:Original post by ZahlmanQuote:Original post by GaiidenI'll even use myself as an example. I think my Art of Code Documentation article is very, very opinionated.Strangely enough, I went to go read that, and found myself disagreeing with almost everything :)I'm going to have to side with Zahlman there, Drew [smile]I hate superfluous comments; code exists to communicate between programmers (including between your current self and your future self, so be nice to your future self and write comprehensible code). Plus, in modern development environments, you need comments, commit logs and related bug entries to comprehensively understand a piece of code without studying it - and that doesn't cover any third-party components or external libraries your code may depend on.Anyway, re tutorials, I'm squarely in the "harmful" camp. The "annotated code dump" style developed and became popular early enough that it's now the norm, but it doesn't promote understanding at all. I'm proud of the fact that I didn't entirely succumb to that when writing my own article, even though I'm embarassed by the code now (but, in my defense, that was five years ago!).At one time we wanted to promote and editorial policy banning annotated code dumps: all programming submissions would need to be accompanied by separate listings (that compile and run, by which rules my own article would not be valid either), with the exception of Sweet Snippets (which are all-code, basically), so that the articles would be compelled to focus on the theory behind the implementation. We still might.Focus on the theory, promote real insight, and your contributions will be celebrated. They may be rejected by clueless beginners who want immediate results, but eventually their value will be indisputably accepted.   ;Quote:Original post by OluseyiQuote:Original post by ZahlmanQuote:Original post by GaiidenI'll even use myself as an example. I think my Art of Code Documentation article is very, very opinionated.Strangely enough, I went to go read that, and found myself disagreeing with almost everything :)I'm going to have to side with Zahlman there, Drew [smile]I'm both happy to know I was right about my own article, and sad that I actually wrote it like that. I'll get around to a re-write soon now that it's back on my radar.Quote:Focus on the theory, promote real insight, and your contributions will be celebrated. They may be rejected by clueless beginners who want immediate results, but eventually their value will be indisputably accepted.I still get fan mail randomly (last email was the end of May) for my Winsock article thanking me for helping them understand the concepts better. So there's my good example to complement my bad example.   ;Quote:Original post by SneftelThey cast game development as a series of discrete skills to have (as though every professional game developer spends his days writing BSP loaders and implementing shadow mapping) at the expense of more generally useful CS theory.Could not possibly agree more, which is actually what prompted me to start writing what I'm writing now [Link to brief description].  It seems an awful lot of the articles/tutorials will cover a specific subject in a manner that makes it difficult to take that knowledge and then apply it to an arbitrary problem.I'm reminded of an unfortunately large number of my computer science classes, specifically the 'projects' they had us do, each of which emphasizing a specific concept in such a closed-off system as to leave the experience it provided you with nearly inapplicable to anything other than that project.Your [all of your] input so far has been very helpful, thanks.Also, the idea of an editorial process applied to new articles sounds very interesting, or at least a review period during which an article can have changes requested of it's author.   ;  We've had a few big discussions about how/why the NeHe tutorials are bad, which are worth a look (although I don't have any links handy).Oluseyi has already pretty much summed it up, although personally I think tutorials are aimed at a too low level of skill and a too broad subject. As a result you end up with OpenGL tutorials explaining how to open a file, and other irrelevant nonsense. A well focused tutorial can be a great help in certain situations (eg. a basic OpenGL walkthough which demonstrates the concepts and syntax for someone already familiar with graphics programming).Quote:Original post by SneftelIn my opinion, 90% of game development tutorials are crap. They don't aid you in understanding the concepts behind code; on the contrary, they encourage a cookbook approach. They cast game development as a series of discrete skills to have (as though every professional game developer spends his days writing BSP loaders and implementing shadow mapping) at the expense of more generally useful CS theory.I believe it was Asimov who said something along the lines of "sure, 90% of sci-fi is crap, but 90% of everything is crap". [grin]   ;  i generally hate code snippets full stop in tutorials (unless obviously it's a tutorial about a language or API)what i want is the tutorial to say the theory behind something and explaining how it's implmented, maybe formulae etc.i don't want code and what pisses me off is a lot of the tutorials these days are based around c#, which i wouldnt care about but they're expecting you to bum the code snippets because they're obviously crap at explaining things and just show you an answer and expect you to work it out yourself, a good tutorial surely is one where you can still learn the underlying theories and methods without even having to code in the same language as the code snippets   