What makes a good tutorial? (& thoughts about general education)

I think about writing a C++ tutorial from time to time, but the problem is: do I write a general C++ tutorial or one aimed at the Pokitto?

I struggle to write tutorials because they tend to be a linear progression of ideas, and I think of C++ in a farily non-linear way.

I’m better at answering specific questions or explaining specific concepts than writing about all the concepts in a meaningful order.

(I’ve considered writing a blog before, but never got round to figuring out how I’d set that up.)

As much as I’d love to be paid to write a book, I doubt it would be very popular outside of these small forum groups.

“Written by Pharap, professional experience: none whatsoever, doesn’t have a degree” isn’t going to look very impressive compared to the books written by people who have worked for companies like EA and Google for 10+ years.

True, but I post so often and create such big text walls that it would take a long time to find it all by digging through my posts. :P

Thankfully on the Pokitto forums most of it is contained in The C++ Language category.

Some concepts require understanding some other ones, right? Looks like a (skill) tree could be of more use than a simple sequence :stuck_out_tongue:

1 Like

non-linear you say, so why keep the guide static? how about a text adventure :wink: or just hyperlink the crap out of it


I have my own little theory of learning and teaching that compares learning to creating a sculpture (from rough shapes to fine details in different areas). Knowledge is definitely not a linear structure, it’s not even a tree, it’s a more general graph. However the path to gaining that knowledge is a different thing.

The problem with tutorials is that the people reading them:

  • Don’t exactly know where they are headed.
  • Have to already invest a lot of mental effort into understanding the topic and don’t have much left to coordinate their “movement” through the knowledge graph without adding a lot of confusion, leading to dead ends etc.

So a tutorial has to be a linear path through the knowledge graph carefully chosen by the guide (the teacher). The problem is that sometimes this linear path involves getting back to meet all prerequisites for the next step etc., so it’s very difficult to create a good tutorial that is short and not difficult to comprehend, while leading to gaining the desired knowledge.

At higher levels (university etc.) I think there are mostly better ways than these linear “courses” – the students here should be given flashlights and maps and allowed to find their own paths (finding your own path is a knowledge/skill of its own, and one of the most useful ones). But that’s actually happening – there is usually a list of recommended literature, which is basically that. Also things like automatically generated code documentation are the same thing – it’s a non-linearly presented knowledge. But for the price of being incomprehensible to beginners.

1 Like

Certainly I think a lot of things you end up revisiting because you learn new ways to apply techniques, so in that respect a skill tree might be a reasonable way of modelling it.

For example, template type aliases depend on knowledge of both templates and type aliases.

That would also be increedibly difficult to write, I think.

I don’t think it’s even acyclic, I think it’s mutually dependent sometimes, or at least every topic requires revisiting.

I’m half and half about this.

With the prices universities charge I’d expect them to be more than just a curator of resources.
Also I think this only really works with students who are really driven.
Some people are capable but can’t succeed without a guiding hand, and a lot of good advice isn’t written down, it just lives in the heads of experienced people.

This is essentially how I learned programming,
by digging through internet resources (I had very little guidance).
That worked for me because I was driven by a desire to know,
but I don’t know how well it would work for others.

Yes, graphs repesenting knowledge e.g. in AIs will have cycles. I was thinking “knowledge” in a sense of how it’s acquired, or its dependencies – that is when there’s a cycle “A needs B and B needs A” I just suppose it’s the same knowledge and merge them… I kind of abstract some detail.

We have publicly funded education in my country (one of only few things I like about it), so I have this image of the responsibility of learning being on students. Sure, when people pay for it, they’ll probably expect something different. But I think the prior case is better (education for the responsible/motivated, not rich).

Of course there are still classes etc., but I see these as a kind of taking the students for a quick flight over the wilderness they’d be released into :slight_smile: This educates the students not only in the given field, but also in self-education, which e.g. in CS is very important as the flood of new technologies will be constant over their whole careers, and there will be no more classes IRL.

I agree, that’s the kind of students that go to universities. You have to be driven in order to get some deeper knowledge.

Not many people can do this indeed, but when you can do it, it’s very effective. As you say, it’s about the drive, the motivation. I wonder what the motivation was for you? For me and many other people I know it was games :slight_smile:

We do for primary and secondary education, but not for college/university level.

Instead we have a system of loans that people have to pay back in installments once they’re earning a certain amount of money, so they’re still effectively paying for it, but not immediately.

Good in theory, but not everyone is responsible or motivated.
I’ve met people nearing their 30s who still don’t know what they want to do with their lives.
Lack of motivation is a big problem here, especially in the poorer areas.

I think part of a teacher’s job is to cultivate interest.
Some teachers can do it and others can’t.

That might be true in other countries, but it’s not true here.
In Britain,
a lot of people treat going to university like it’s ‘par for the course’.
They do it solely because they think they need a university level qualification to get a good job,
and then they end up working in a supermarket despite having a degree.
(Apparently 64% of British uni graduates believe their degrees aren’t relevant to their job.)

Guilty as charged :P

But everyone in my class (moreso in the first course, but also in the second course) loved video games,
so there must be more to it than that, because not everyone left with skills suitable for creating video games.

I’ve heard of it, more than once here on the Internet :slight_smile: I don’t like it, it must be very stressful for the people.

(EDIT: @Pharap educated me on the specifics of the loan and I don’t think it’s that “cruel” anymore, but I still prefer state-paid education. )

I think you can’t really get a real higher education unless you’re really motivated. You can buy a degree, but these degrees are really just a piece of paper, and the person then typically lacks the other traits of higher education (other than the knowledge of the field), e.g. the skill of self-education, critical thinking etc. Because such schools simply guide the students very carefully towards the degree, like in elementary/high school.

That’s why I’m not a fan of paying for education – because it can’t be bought.

Definitely heard of this too. The fact that employers are looking for people with experience and a degree isn’t enough to them to employ a person is an evidence that the education system fails really badly – the degree doesn’t imply the abilities that it should – and I think it’s a lot due to the “pay for education” system.

In my country a degree, even just Bachelor’s, is enough to get you a job (depends on the area of course, but e.g. with CS job offers are simply flying at you, even if you have zero work experience).

Also let’s get back on topic. I think what makes a good tutorial is mostly this (mostly general guidelines for articles or technical text):

  • Briefness, by which I mean real briefness. Consider every single sentence and word. Intro should be just one sentence at most, no one cares about that. The tutorial doesn’t necessarily have to be super short, but has to be condensed. I always look for the shortest tutorial on given topic first.
  • Structure – whenever something can be a list with sublists or a picture or a table, it should be so. That’s how things are stored in our brains.
  • Use emphasis – it helps very much to skim through the text, find what you’re looking for, not get lost, get attention to important terms. It can make up for long text.
  • At each point the reader should learn something immediately useful. The “just remember this, we’ll need this later” is not very good and tends to be discouraging. The “it all comes together only at the end” kind of tutorials should be avoided in my view.
  • Avoid jumping back and forth as much as possible. Try to make a “forward only” tutorial.

Maybe someone should make a tutorial on how to make a good tutorial :slight_smile:

Ok, I’ll reply to the other matter in a PM.

This sounds like we’re getting into barber/mailman paradox territory.
(Who writes the tutorial for writing ‘the tutorial for writing tutorials’.)