Improving Tutorials

[Cervantes]

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!

[Cervantes]

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?

[AsianSensation]

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?

[Cervantes]

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.

[TokenHerbz]

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???

[Cervantes]

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.

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.

[TokenHerbz]

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

[Cervantes]

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.

[ZeroPaladn]

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.

[Tony]

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.

[Cervantes]

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.

[wtd]

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.

[zylum]

me too

[ZeroPaladn]

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.)

[ZeroPaladn]

allright, the basic part of the tut is done, cervantes. if it needs anymore upgrading jsut tell me.