How to write tutorials for beginners ?

[deltarho[1859]]

Dunning–Kruger effect

In a nutshell it could be described as "The more incompetent someone is the more likely they are to over estimate their competence".

If I was to embark on writing a tutorial on anything I would not dream of publishing it before it was subject to peer review. An incompetent person would not do that. I would revise my tutorial in accordance with a consensus of opinion. At some point a decision to publish must be made and I would make that and assume full responsibility for it. The tutorial would include a list of credits which may instil a level of confidence in the readership.

I have only been at this forum for 10 months but I have a clear idea who my preferred peers would be. I would contact them and ask if they could spare the time to consider my tutorial with a critical eye. The tutorial would invite readers to comment. My response would also be subject to peer review.

My tutorial would be an absolute cracker. <smile>

Added: There is a corollary to the Dunning-Kruger effect which, in a nutshell, could be described as "The more competent someone is the more likely they are to over estimate the competence in others". For such individuals peer review is probably more important.

In either case then peer review should prove a worthwhile venture.

This post could be described in a nutshell. Writing tutorials is a big responsibility and should be undertaken in a professional manner.

[dodicat]

I absolutely agree with you deltarho[1859],

Fool's Paradise is a great place to be at, and I would never ever wish to leave it.
Tay, Tay, the beautiful Tay.
It flows through Dundee every day.
(McGonnegal ~ish)
<cracking>

[deltarho[1859]]

@dodicat

I added a bit.
---------------------------

I lived in Dundee for nearly a year when I was a young man. I attended many a drinking session and was extremely lucky - I only fell into the Tay once. <laugh>

[BasicCoder2]

I don't understand you, about 2 years ago, when we where discussing Draw-Editor's,you've used relative positioning, all the time?

Probably I didn't use STEP in the LINE command. I have no issue with it just for some reason I never used it.
For example this draws a line in a rotated polygon from a list of relative positions.

Code: Select all

Line temp,(rx(i)*sizeOfPlane+mx,ry(i)*sizeOfPlane+my)-(rx(i+1)*sizeOfPlane+mx,ry(i+1)*sizeOfPlane+my),rgb(0,0,0)

I would probably use a type now instead of parallel arrays.

[BasicCoder2]

@deltarho[1859],
However you will probably never write that cracker tutorial so what to do in the mean time?
The thread started when I was thinking about the types of tutorials I like after the suggestion FreeBASIC needs them.
Some competent people dream about that great house they could build but never actually build it.
Some incompetent people build the house and although not anywhere as good as the competent person could have built at least they have a house people can live in. To be critical of the rubbish house they built is easy. Building one yourself is hard.
It is the student that gets to decide if they understand the tutorial or are motivated by it.
.

[deltarho[1859]]

However you will probably never write that cracker tutorial

It is almost certain that I will not.

At some point a decision to publish must be made

That is where I would fail. My peers would have to 'gang up' on me. "David, we know that your are not satisfied but we are and we are ruling to publish"

It is the student that gets to decide if they understand the tutorial ...

That is twice that has been said. A faulty tutorial may be understood but the student may not be in a position to realise that it is faulty. Understanding a faulty tutorial does not correct it. MrSwiss and fxm took the opening code to task. A peer reviewed tutorial is less likely to be faulty.

I have extended the two nutshells - see the italic additions.

"The more incompetent someone is the more likely they are to over estimate their competence and under estimate the competence of others."

"The more competent someone is the more likely they are to over estimate the competence in others and under estimate the competence of themselves."

On a final note, architects do not build buildings, structural engineers do.

[BasicCoder2]

@deltarho[1859],
The first post itself was not meant as a tutorial although I can see that may have been a reasonable assumption based on the subject title. The point may have been lost but now I have lost interest in the subject anyway and just accept that there will be no beginner or intermediate level tutorials happening for FreeBASIC as there are for other programming languages on the internet such as the utube metaball example I was trying to translate.
.

[paul doe]

@deltarho[1859],
The first post itself was not meant as a tutorial although I can see that may have been a reasonable assumption based on the subject title. The point may have been lost but now I have lost interest in the subject anyway and just accept that there will be no beginner or intermediate level tutorials happening for FreeBASIC as there are for other programming languages on the internet such as the utube metaball example I was trying to translate.
.

Why have you lost interest? It's coming along fine! Just finish translating it (so you have a better understanding of the algorithm), and then you can refactor it, if you want. Can I be of any help?

[Carlos Herrera]

As a mathusalemic newbe and beginner forever I would like to state the following:
1. All we need are tutorials on GUI programming.
2. Very good example is Introduction to GUI Programming with FLTK
by Lothar Schirm (step by step introduction of widgets, clean and elegant coding style,...).
3. Shared variables are very useful and therefore unavoidable in GUI programming,
see p.2

[BasicCoder2]

Why have you lost interest? It's coming along fine! Just finish translating it (so you have a better understanding of the algorithm), and then you can refactor it, if you want. Can I be of any help?

The metaballs were just an example of how I like something to be explained in incremental steps as shown in the video. I was doing a FreeBASIC copy of the utube video but it became instead about best practice in programming.

What makes you interested in any particular thing at any particular time is unknown. You just feel like it at the time.
.

[lizard]

1. All we need are tutorials on GUI programming.

Sure? But what do you do with a GUI without any content?

[deltarho[1859]]

Hmmm. I was getting the impression that any tutorial was better than no tutorial. To my mind that is a false premise. With no tutorial a student will be forced to read the manual, will be forced to search the forum archives and , horror of horrors, be forced to write failing code snippets over and over until they got it right. If all that failed they could come here for help. I think I may have just put up a case for no tutorials. <laugh>

Having said that, I would not ignore a well written tutorial. If a graphics tutorial was written by dafhi and peer reviewed by dodicat, paul doe and a few other gfx guys and I fancied getting into graphics then I would probably do well to read it. On the other hand a badly written graphics tutorial would be the last thing that I should read.

Being a novice at graphics I would benefit, BasicCoder2, from incremental steps. They could be dispensed with at 'Graphics Tutorial Part III' or whatever.

@Carlos Herrera

If you download Paul Squires' WinFBE and click on the down chevron next to the New icon you will find a lot of Windows GUI templates by José Roca. They are not SDK templates but all the code is underpinned by the SDK. After a very short while you will be 'knocking out' some very respectable GUI apps. Admittedly, you will probably be doing a lot of 'Copy and Paste' with your eagerness to get something up and running but if you examined your final product you will get a feel for Windows GUI programming. Anybody wanting to get into Windows GUI programming should consider getting a copy of 'Programming Windows' by Charles Petzold. I have the fifth edition written in 1999. A paperback version will knock you back £15.83 at Amazon UK. The hard back version costs £32.87. That may seem ancient but subjects like messages, for example, are pretty much the same as ever they were. What I did not know was that a sixth edition was published in 2013 for 'Writing Windows 8 Apps with C# and XAML'. I shall give that a miss - £66.12 for a paperback - yeah, right!

I should add that I am not an accomplished SDK programmer. At PowerBASIC I used Dynamic Dialog Tools (DDT). That is not a SDK replacement but it covers a very high percentage of what a GUI app would need. Occasionally, I needed to do something that DDT did not cover. That saw me going to MSDN to read up on a Win32 API. José's work is analogous to DDT.

Sure? But what do you do with a GUI without any content?

Well, you could wash your car with it. Alternatively, you could transfer some console code just to get started.

[dodicat]

Basiccoder2.
In your very first example:

Code: Select all

const SCRW = 640
const SCRH = 480
screenres 640,480,32  'set up window

sub drawIt()
    dim as single dx,dy,d
    for x as integer = 0 to SCRW-1
        for y as integer = 0 to SCRH-1
            dx = abs(x - SCRW/2)
            dy = abs(y - SCRH/2)
            d = sqr(dx^2 + dy^2)
            if d > 255 then d = 255
            pset(x,y), rgb(d,d,d)  'each color a function of x and y
        next y
    next x
end sub

drawIt()

sleep 

I would say that it is pretty easy to follow.
A couple of points though, which I am not sure would benefit it at all.

1) abs is not needed because you are squaring dx and dy anyway which will always give the positive value.
2) dx*dx would be faster than dx^2 --
(Also perhaps SCRW/2 could be pre- computed so not to do the calculations each time).

Point 1) could perhaps be adjusted.
Point 2) perhaps need not be, it is only a computer optimisation, and probably easier to follow the way you have it.

But I think that graphical demos are a great way to attract interest in freebasic, because graphics are a freebasic asset.
(Try writing the meatballs demo in pascal)

[BasicCoder2]

1) abs is not needed because you are squaring dx and dy anyway which will always give the positive value.

True in this case. In other cases keeping the signed result would also be desired.

2) dx*dx would be faster than dx^2 --

This would only be known if told or measured.

(Also perhaps SCRW/2 could be pre- computed so not to do the calculations each time).

Looking for computations to take out of loops is an important thing to learn as the speed difference can become significant.
This I would see as part of incremental learning although in my case I keep forgetting what I have learnt!!

(Try writing the meatballs demo in pascal)

I think the person in the utube uses some language called processing or javascript.
I haven't learnt those languages but in this case was able to translate.
The translation between languages interests me. A professional programmer ultimately has to deal with a number of languages even if that means they have to learn them all. Something I guess Europeans must do with human languages.
.

[Carlos Herrera]

1. All we need are tutorials on GUI programming.

Sure? But what do you do with a GUI without any content?

You missed the point, the problem is what to do with lot of content without any simple GUI.

@deltarho
How many pages have the book of Petzold? Is it written with a tutorial for beginners style?
Is Freebasic mentioned there?