Posted: 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.
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!
Sponsor Sponsor
Cervantes
Posted: Wed Aug 17, 2005 7:44 am Post subject: (No 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?
AsianSensation
Posted: Wed Aug 17, 2005 10:07 am Post subject: (No 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?
Cervantes
Posted: Wed Aug 17, 2005 12:08 pm Post subject: (No 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.
TokenHerbz
Posted: Wed Oct 12, 2005 11:45 am Post subject: (No 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???
Cervantes
Posted: Wed Oct 12, 2005 3:40 pm Post subject: (No 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.
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
Posted: Wed Oct 12, 2005 11:15 pm Post subject: (No 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
Cervantes
Posted: Thu Oct 13, 2005 3:37 pm Post subject: (No 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.
Sponsor Sponsor
ZeroPaladn
Posted: Mon Dec 05, 2005 2:32 pm Post subject: (No 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.
Tony
Posted: Mon Dec 05, 2005 2:49 pm Post subject: (No 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.
Posted: Mon Dec 05, 2005 5:03 pm Post subject: (No 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.
wtd
Posted: Mon Dec 05, 2005 5:45 pm Post subject: (No 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.
zylum
Posted: Tue Dec 06, 2005 12:58 am Post subject: (No subject)
me too
ZeroPaladn
Posted: Wed Dec 07, 2005 10:21 am Post subject: (No 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.)
ZeroPaladn
Posted: Fri Dec 09, 2005 9:53 am Post subject: (No subject)
allright, the basic part of the tut is done, cervantes. if it needs anymore upgrading jsut tell me.