Programming C, C++, Java, PHP, Ruby, Turing, VB
Computer Science Canada 
Programming C, C++, Java, PHP, Ruby, Turing, VB  

Username:   Password: 
 RegisterRegister   
 Improving Tutorials
Index -> Programming, Turing -> Turing Tutorials
Goto page 1, 2, 3  Next
View previous topic Printable versionDownload TopicRate TopicSubscribe to this topicPrivate MessagesRefresh page View next topic
Author Message
Cervantes




PostPosted: 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!
Sponsor
Sponsor
Sponsor
sponsor
Cervantes




PostPosted: 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




PostPosted: 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




PostPosted: 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. Smile
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. Wink
TokenHerbz




PostPosted: 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




PostPosted: 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. 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.
TokenHerbz




PostPosted: 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 Smile
Cervantes




PostPosted: 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
Sponsor
sponsor
ZeroPaladn




PostPosted: 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




PostPosted: 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.
Latest from compsci.ca/blog: Tony's programming blog. DWITE - a programming contest.
Cervantes




PostPosted: 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




PostPosted: 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




PostPosted: Tue Dec 06, 2005 12:58 am   Post subject: (No subject)

me too Razz
ZeroPaladn




PostPosted: 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




PostPosted: 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.
Display posts from previous:   
   Index -> Programming, Turing -> Turing Tutorials
View previous topic Tell A FriendPrintable versionDownload TopicRate TopicSubscribe to this topicPrivate MessagesRefresh page View next topic

Page 1 of 3  [ 43 Posts ]
Goto page 1, 2, 3  Next
Jump to:   


Style:  
Search: