Funny subject eh? I thought I might as well repost this here instead of rewriting the wheel as it were, most tutorials in the gaming world are lacking, they must be done over and over to stick, if each of them read this page once it would help the gaming world as a whole. Source: http://treehouseideas.com/article.page What's the most important thing to remember when writing a tutorial? Remember you're teaching a new idea, not just documenting it. Maximize comprehension. Write in a way that helps them build the idea, not the rules. Syntax can always be looked up. With a concept model in their head, your student can recreate the idea in any way they want. Writing in a dull, dry, disconnected, "take it or leave it" kind of way will cause your reader to zone out. My experience is that there are some people who can learn even when the presentation is horrible, but there are smart people that don't learn as easily. If you want to reach all the good people, you have to write as if your students are humans, not computers. How do you go about it? These are some basic ideas, just suggestions. The goal is to develop an instinct for teaching, not just run down a checklist each time you write. Write in a way you'd talk to someone This one is critical, so I'm going to spend a bit more time on it. There's a big difference in tone for a good novel and good tutorial. In a tutorial, simplify the language and grammar so that the reader can focus brainpower on the concept. The more common, personal and direct the words are, the more automatic the reading is. Let them sail through the text. If your sentence structure would fit in normal conversation, you're on track. If your paragraphs read like "Shakespeare's Guide to XML," go back to the drawing board. Code: Fundamental aspects of the object-oriented software design include encapsulation, inheritance, composition, and polymorphism. Each of the aforementioned terms represent solutions to managing particular areas of difficulty in computer science. Another area of discussion involves the typing system employed by the compiler and runtime system. The ramifications of employing static or dynamic typing as related to data structure integrity is a quite involved topic, and is conducive to further discussion. Good [modern Mark Twain]: Code: Some terms you'll see in object-oriented programming: * encapsulation * inheritance * compositing * polymorphism There's no need to memorize them. They're big words for very simple ideas which will become second nature to you. I'll go over each, one by one. We'll also cover 'dynamic' vs 'static' typing. The Mark Twain example makes sense the first time you read it. The grammar isn't creating artificial speed bumps. In software development, simple code is better than complex code that performs the same task. Why? Because it's easier for you and everyone else to understand. Works the same for tutorials. Get to the Point Be direct. Skip the history lessons. Ditch the three paragraph anecdotes. Relating your Aunt Millie and her apple pies to an database access manager may actually aide comprehension, but only if you get it done in a sentence or two. Funny and entertaining is good, rambling is bad. Write the anti-novel. Results Early If you're having the reader build an app or configure a server process, do a simple example right away. This will get them hooked, and keeps you (the author) focused. If you ramble for three pages, you'll lose your audience. Get to an example right away, then explain it. Recap Frequently You're trying to teach a complex idea. The brain can't necessarily absorb it all at once. Bring earlier concepts back and show how they fit into the big picture. This helps the brain from being overwhelmed, which means faster learning. You're not wasting time or space. The overriding goal is comprehension. Briefly review earlier material. Visually Separate Text In a classroom, the teacher doesn't stand up and talk for ninety minutes straight. Pauses in speech are used for emphasis and to allow ideas to sink in. Since you're not there in person, give the reader cues to pause. Whitespace or visuals work well. And double-space the text to prevent sentences from running together. Smart formatting means easier reading. Gotta Make it Fun If you want to accelerate reading and comprehension, make it fun. Fun has a VIP pass to the center of the brain. Wrap the details in something more lighthearted. Or if not fun, how about just less dry? Try "get all your objects together" instead of "use the proper collection API to consolidate your data structures." You can obsess about sounding professional, or you can do whatever it takes to teach. Your choice. Fun = efficient learning. Finally: Remember Sesame Street Kids absorb information like crazy, but it might be partially due to how it's presented to them. Sesame Street's format is ideal for teaching students of any age. A few key ideas are covered in a number of different ways: visuals, music, conversation, puppets, etc. Not everyone learns in the same way. Stimulation and variety succeed. The link between stimulation and learning doesn't just vanish when we get older. Stimulate and engage the reader's brain.
it makes sense i realy agree about the tutorail i think thats a good way to make a tutorial:beerbang: :beerbang: :beerbang: :beers:
