Computer Science Canada

Improving Tutorials

Author:

Cervantes [ Sat Aug 13, 2005 11:28 am ]

Post subject:

Improving Tutorials

Improving Turing Tutorials

CompSci.ca is all about teaching computer science. Since it is centred around Turing, we should have excellent Turing tutorials to achieve that goal. Sadly, we don't. Many tutorials leave lots of room for improvement. As a community, I hope we can fill those gaps.
Having great source code is good, but having great tutorials is better.

If you wish to help CompSci.ca by improving a tutorial, follow these steps:

Post here, specifying which tutorial you are interested in improving.
Wait for the staff to carefully look over the tutorial and decide what needs to be changed/added. This will mostly be in the form of additional sub-topics to add to the tutorial.
Wait for a Turing mod to send you the BBCode of the existing tutorial, so you don't have to redo everything yourself (though you can! In which case, you don't have to bother waiting for us.)
Write the tutorial.
PM the new BBCode to me, and wait for my reply. You will either get the go-ahead to post the new tutorial, or be asked for some more modifications, in which case go back one step.

Tutorials will have certain requirements placed on them. They must:

have good, well-commented example(s). The more the merrier.
pose questions for readers to solve on their own.
supply answers to these questions at the end of the tutorial.
be formatted well. Introduction, body, conclusion. The body should be split up into sub-topics.
use headers.
bold key terms.

A good looking tutorial is always nice. Your tutorial will double as eye-candy if you add some colour.

Here is a list of tutorials that need updates the most, in no particular order. Note that these were picked not only based on their quality, but also their importance. A very important topic (such as classes) that is only a decent tutorial should be upgraded.

Pointers by lyam_kaskade

Content covers points well, but does not explain too deeply.
Start from the beginning of the topic, with examples along the way.
Format needs work
Some parts are a little tart
Good use of examples

Collision Detection by Hacker Dan
Good content, not much explanation.
Format is almost there, but doesn't have the whole step-by-step idea that has worked well in recent tuts.
Reads well, until the code whose var names could be a bit better...this is just a technicality though.
Example present.

Buttons by recneps
Content covers basics, doesn't go into CreateButtonFull, does a decent job of explanations. A very particulate topic.
Would be nice if it covered more of Turing's GUI.
Format needs a lot of work
Reads alright
Examples do the job.

Input.KeyDown by Tony
Well covered, get's the basics of char control. Some more advanced areas like Flushing could be introduced as well.
Format needs work
Reads decently
Example works, does its job.

Simple Draw Commands by Asok
Not bad content.
Format needs a lot of work.
Reads well.
Examples aren't half bad. Could be a little more extensive though.

Movement (getch, keydown, mouse) by DanShadow
content is greatly lacking
format is decent. Were it longer and more detailed, it would require more formatting
readable
example included

Font.Drawing by .hack
content should be largely revamped
should delve into Font.Width
format is lacking
readability is decent. Needs [code] or [syntax] tags
no examples

Whatdotcolour by Andy
content is decent
format is lacking
readability is very poor
example present

This list constitutes the first round of improvements. When these are almost done, I will post the second round.

For producing great tutorials, you will be showered with bits. I'm thinking upwards of 200 BITS for a single, quality submission.
Make these tutorials count!

Author:	Cervantes [ Wed Aug 17, 2005 7:44 am ]
Post subject:
Today, I'll try to revamp the types and records tutorial. If anyone has any suggestions as to what they would like to see added, post away. I will walk through how types work with more clarity, try to give more examples, show how to use init with records, and show a little more advanced use of types, such as functions that return a user-defined type. Anything else?

Author:	AsianSensation [ Wed Aug 17, 2005 10:07 am ]
Post subject:
No!!!! I didn't post yet, but I'm like 90% done completely revamping the records tutorial. Sorry Cervantes, should have told you earlier. You can add to it if you feel like it once it's finished, but let's not both rewrite this, eh?

Author:	Cervantes [ Wed Aug 17, 2005 12:08 pm ]
Post subject:
Tsk tsk, not following the rules. That's alright, I didn't start writing it yet. Could you cover unions in your tutorial? They aren't hard; I'm just having trouble thinking of a good example to give with them. In this case, I'll switch to improving the first tutorial: put, get, vars. Should be interesting.

Author:	TokenHerbz [ Wed Oct 12, 2005 11:45 am ]
Post subject:
is ther a really EASY tut i can make??? i could use the bits... my knoledge of turing isn't mind bogling though, so im thinking loops, for's and if's... stuff like that, what do you think???

Author:

Cervantes [ Wed Oct 12, 2005 3:40 pm ]

Post subject:

tokenherbz wrote:

im thinking loops, for's and if's... stuff like that, what do you think???

You could try to improve Tony's If-statement tutorial.

Things to do:
Give an introduction. Talk about why we need to compare things. Use English to explain if statements first.

Then delve into the first basic if statement.

code:

var bool : boolean := true
if bool then
put "Condition satisfied. Entering the if statement...
end if

Explain how the value of bool, true, is inserted into 'bool' in the if statement, so it essentially reads "if true then". An if true then statement is always entered. An if false then statement is never entered.

Explain how this could be re-written as:

code:

var bool : boolean := true
if bool = true then
put "Condition satisfied. Entering the if statement...
end if

This uses the = comparison to check if true = true. It does, so the if statement is entered.

Expand this to other types of variables. Integers, reals, and chars should do for now.

Introduce else. Use english to explain it first.

Introduce other comparison operators:
<
>
<=
>=
Make sure the else is understood for these operators as well. For example:

code:

var num : int := 4
if num > 4 then
put "The number is greater than 4."
else
put "The number is less than or equal to 4."
end if

Question time. Find the biggest of two numbers.

Next, talk about logical operators: and, or, not. Talk briefly about the precedence of them.

Introduce elsif. I suggest this is done by first showing some code that solves a problem (such as finding the biggest of three numbers) and that uses else's followed by new if statements, like this:

code:

if condition_a then

else
if condition_b then

end if
end if

Then introduce elsif's and show how they ease up the coding. Explain that you can have as many elsif's in an if structure as you like.

Question time. Find the largest of 4 numbers.

Conclude. Why we need if statements. Recap comparison and logical operators. Link to the loops tutorial.

The above structure is a representation of my thoughts alone. Please, comment and improve. Smile

Tokenherbz: If you still want to do this, PM me and I'll send you what Tony has done so far. Or you could start from fresh. That's probably the better idea, so that it's all in the same style.

Author:	TokenHerbz [ Wed Oct 12, 2005 11:15 pm ]
Post subject:
Ok, i will start anew... Though, i dont know how to "modify" text's, use colors, or make the letters bigger in the tut, So, i will edit it later yes?? I will start now, save it, and PM you the copy so you can help me add missing info / spell check etc:: 4 eyes are better then 2

Author:	Cervantes [ Thu Oct 13, 2005 3:37 pm ]
Post subject:
Ack! I don't mean to offend, but that's not an improvment. Okay, maybe I wasn't clear enough. Look in those mini "reviews" of the tutorials Delos and I decided needed improving. See how most of them have a comment about the readability? That is a rating of how easy it is to read the tutorial: not in terms of difficulty of the content, but spelling, grammar, how well structured your sentances are, if you even have sentances, etc. My point is that your tutorial needs to be cleaned up. Spelling mistakes, remove ellipses (...), nice, readable paragraphs. Headers. A little more formality. If you don't understand what I'm saying, check out this tutorial. It also needs to follow a better detailed structure. I think the one I posted above works pretty well. Also, why did you assume the programmers knew about loops? In the walkthrough and in most computer science classes (AFAIK), if statements are taught before loops. tokenherbz wrote: Though, i dont know how to "modify" text's, use colors, or make the letters bigger in the tut, See the buttons above the reply box? Click them to learn. tokenherbz wrote: So, i will edit it later yes?? Then why did you post it? I've deleted it, and you can repost it when it is ready. You skipped the last step of the process: Cervantes wrote: PM the new BBCode to me, and wait for my reply. You will either get the go-ahead to post the new tutorial, or be asked for some more modifications, in which case go back one step.

Author:	ZeroPaladn [ Mon Dec 05, 2005 2:32 pm ]
Post subject:
i could rewrite the Simple Draw Commands Tutorial, those are the one thing im good at. Ill start from scratch, id prefer it that way.

Author:	Tony [ Mon Dec 05, 2005 2:49 pm ]
Post subject:
you could go ahead with tutorials from scratch. Just make sure they are marginally better, otherwise we'll just end up with multiple instances of essensially the same thing.

Author:	Cervantes [ Mon Dec 05, 2005 5:03 pm ]
Post subject:
Tony wrote: Just make sure they are marginally better, otherwise we'll just end up with multiple instances of essensially the same thing. Any sort of improvement is good, true. But if you're going to go to the trouble of making a tutorial on an already existing topic, you might as well make it a lot better. A fair portion of your time will be getting to a point where your tutorial in progress is as good as the previous tutorial. Since you've already spent a fair amount of time, it doesn't make much sense to spend another few minutes to make your tutorial marginally better. Might as well spend another hour and make it truly superb.

Author:	wtd [ Mon Dec 05, 2005 5:45 pm ]
Post subject:
Write new tutorials in a text editor outside of the web browser. That will give you the ability to continue refining it without being tempted to hit submit. This is how I work.

Author:	zylum [ Tue Dec 06, 2005 12:58 am ]
Post subject:
me too

Author:	ZeroPaladn [ Wed Dec 07, 2005 10:21 am ]
Post subject:
aight, ill get started. might as well take a look at the previous one, see if theres anything i can salvage (giving credit where its due of course.)

Author:	ZeroPaladn [ Fri Dec 09, 2005 9:53 am ]
Post subject:
allright, the basic part of the tut is done, cervantes. if it needs anymore upgrading jsut tell me.

Author:	Cervantes [ Sat Dec 24, 2005 1:32 pm ]
Post subject:
Any progress on part II, ZeroPaladn? I'm going to start improving a tutorial today. It's going to be the if-else-elsif tutorial, since I've already planned the whole thing out a few posts up. Edit: It's going to be a while: it's on an ext3 partition, so it's going to have to wait for me to re-install linux, which I'm not in a huge rush to do at the moment. Now that we've all got some time off, I expect some progress!

Author:	Cervantes [ Thu Dec 29, 2005 12:45 pm ]
Post subject:
As per the above post's edit, I'm putting the if tutorial off for a bit. I've moved on to the classes tutorial, and it will be in two parts. Part I is the basics of classes. Part II is inheritence and polymorphism. Part II will revolve around making the item system for an RPG. Should be interesting. There are some easy topics that can be re-tutorialized here, guys: arrays, file I/O, Input.KeyDown, Font.Draw... Those of you who are knowledgable with the topics, can communicate effectively, and can type could fire off a quality tutorial in two or three hours. And writing tutorials can be fun.

Author:	do_pete [ Mon Jan 02, 2006 1:50 am ]
Post subject:
Since no one's done one I think I'll write a Dir tutorial

Author:	Cervantes [ Mon Jan 02, 2006 9:16 am ]
Post subject:
Excellent! If you can work it in, some of the File module has not been covered as well. Turing Reference wrote: Exists Returns whether a file exists. FullPath Returns the full absolute path name of a file. Parent Returns the parent directory of a file or directory. Status Gets information about a file such as size, modification date, etc. Copy Copies a file to another location. Rename Renames a file or directory. Delete Deletes a file. DiskFree Gets the free space on the disk upon which a file or directory resides. Most of that could fit into the tutorial, I guess. And it wouldn't take much explaining either. Perhaps one section about the File module would be enough. Thanks do_pete. I hope it turns out great.

Author:	ecliptical [ Mon Jan 02, 2006 9:36 am ]
Post subject:
As soon as my host resolves the 406 Error I get when tryin to access stuff on the server I'm renting I'll post a Online Highscore tutorial.

Author:	do_pete [ Mon Jan 02, 2006 12:07 pm ]
Post subject:
OK I'll include part of the File module in my tutorial

Author:	Cervantes [ Mon Jan 02, 2006 5:22 pm ]
Post subject:
Sounds good. ecliptical: That's okay, but you should know that we already have two tutorials on the topic (though one of them doesn't really count). http://www.compsci.ca/v2/viewtopic.php?t=5340 http://www.compsci.ca/v2/viewtopic.php?t=7499 Of course no one's going to stop you from writing a tutorial on the topic, but remember that your time will go to waste unless it's better than the competition. Edit: An online high score system, you say? Does that mean you'll be covering the Net module as well? (Although that does deserve its own tutorial.)

Author:	ecliptical [ Mon Jan 02, 2006 6:02 pm ]
Post subject:
Yes it does include the Net module and it's actually surprisingly simple and reliable.

Author:	DIIST [ Sun May 14, 2006 10:47 am ]
Post subject:
Can you make a tutorial into an animation instead of typing anything up! it easier to understand when you see,plus it'll save some of us who arnt good in english.

Author:	ZeroPaladn [ Thu May 25, 2006 12:03 pm ]
Post subject:
I've gotten back to the Draw Tutorial (sorry for the holdup) and it is going pretty good, still trying to make it so that it is half decent if not better, because Ive never been good at conveying information to others .

Author:	richcash [ Mon Aug 28, 2006 5:32 pm ]
Post subject:
Hey, do you still need tutorials improved, because I'm really interested and I have extra time. I'm especially interested in improving the collision detection tutorial included in the Turing Walkthrough because it is really old, so it would be good if someone could tell me if that still needs to be improved. I can also improve other tutorials, but I need an updated list because some of these tutorials have already been done. Also, if there are some tutorials that haven't been done yet, I would be interested in those too. Thanks!

Author:	Clayton [ Mon Aug 28, 2006 8:34 pm ]
Post subject:
im sure you could start improving the collision detection tutorial, just make sure you: Follow the guidelines from the first post (look at other tuts in the Turing Walkthrough if you have to) Get it approved by a mod before you post it HAVE CORRECT SPELLING, PUNCTUATION, and GRAMMAR PLZ! pm Cervantes as well to let him know that you are doing the tut, and im sure he will PM you the actual original post (if you want to) with all of the BBCode disabled

Author:	Ultrahex [ Mon Aug 28, 2006 8:50 pm ]
Post subject:
Im Planning on Redoing the IF-Then-Else By Tony Don't Bother Sending me the BBcode im starting from scratch i so far have about 5 examples and i made sure to INCLUDE all the Boolean Operators (including xor) I Also plan to include a very short peice on what Boolean Operators do and the effect they have, such as they return either true or false Then A List of All The Operators with there shortforms in a list form with green text after showing there meaning Followed By Pre-Explained Examples As Well as Questions Posed With Answers Written in White so you have to highlight in order to see properly at the bottom of the tutorial Then Have Some Programs For Them To Write (Ideas for them to write to understand the concept) This should be complete by the end of week before School Starts (Well School for me starts anyhow) maybe even earlier. (Cervantes If you still come on IRC give me a msg and ill show you what i have)

Author:	richcash [ Mon Aug 28, 2006 9:14 pm ]
Post subject:
Yes, I guess I'm going to improve the collision detection tutorial, so I'm notifying everyone of that here. I won't need the BBCode, like ultrahex, I'll just re-write it. I'll PM Cervantes to ask for permission to make it official!

Author:	Cervantes [ Wed Aug 30, 2006 9:35 pm ]
Post subject:
Ultrahex and richcash: Both sound excellent! Thanks!

Author:	ericfourfour [ Mon Sep 04, 2006 1:16 am ]
Post subject:
I was wondering if I could do a tutorial on pointers. I know there already is one but that is just about linked lists and it really doesn't go into what pointers actually are and where they can be used (other than classes and collections).

Author:	Cervantes [ Mon Sep 04, 2006 9:38 am ]
Post subject:
Absolutely! If you want, you could link your tutorial to the existing one (lyam_kaskade's?) so you don't have to rewrite the linked list stuff. If you want.

Author:	ericfourfour [ Mon Sep 04, 2006 10:34 am ]
Post subject:
Okay, I'll get started some time this week when I have the time (new school year).

Author:	CodeMonkey2000 [ Sat Jan 20, 2007 9:20 pm ]
Post subject:	RE:Improving Tutorials
The 2d tiling tutorial needs to be updated and fixed. It needs to be more clear, and needs to explain how to do scroling and colliding.

Author:	Nick [ Mon Jan 28, 2008 2:20 am ]
Post subject:	RE:Improving Tutorials
do we have a joystick module? if so can you send me it so I can see if I can improve if not can I have the green light to write one? I'm not seeing it in the Turing Walkthrough

Author:	Cervantes [ Mon Jan 28, 2008 6:34 pm ]
Post subject:	RE:Improving Tutorials
We don't have a tutorial on joystick use. You absolutely have the green light!

Author:	BigBear [ Wed Feb 06, 2008 3:41 pm ]
Post subject:	Re: Improving Tutorials
I have seen some questions that require using counts. I was wondering if I could make a tutorial on using counts. Or is this too simple and been explain enough?

Author:	michaelp [ Wed Feb 06, 2008 4:32 pm ]
Post subject:	RE:Improving Tutorials
If you wanted to, go ahead. If you think it's too simple of a topic, then add another part of Turing into the tutorial. Nothing wrong with helping people.

Author:	riveryu [ Sat Feb 16, 2008 7:26 pm ]
Post subject:	Re: Improving Tutorials
Matching with my tiny amount of experience with Turing, there is one tiny detail that was left out in nearly all the tuts involving choice of using int and real: - real inTuring automatically generate scientific notation as output where as int doesnt sample situation : Fcns and Proc tut ...blah... Recursion Factorial Example - it used int for the factorial function, where as it cannot go above 12!, while real can output larger numbers althought not exact second sample : The Basics tut Variable Types int - whole numbers, positive negative blah... real - decimals, positive negative blah... - nvr mentioned that advantage Clayton told me about this in my question in Turing Help about "Overflow in Integer expression". (Sry, I accidentally posted this same suggestion about tutorials in the help section.) Maybe this is too obvious to add in, if so, u can ignore this tiny movement and move on with ur Turing tutorial revolutions....

Author:	anna12345 [ Tue Apr 29, 2008 8:41 am ]
Post subject:	Re: Improving Tutorials
can someone explain me what is high score for and how do you create it?

Author:	Nick [ Tue Apr 29, 2008 3:45 pm ]
Post subject:	RE:Improving Tutorials
yes

Author:	shri [ Sun Jun 07, 2009 12:06 pm ]
Post subject:	RE:Improving Tutorials
do u no how to make a jeopardy game...on turing

Author:	MrConBeans [ Fri Jun 03, 2011 11:31 am ]
Post subject:	Re: Improving Tutorials
How About Music and how to play music

You can syndicate this boards posts using the file backend.php or view the topic map using sitemap.php.

Terms of Use | Privacy Policy