Live data from Hacker News

Ask HN: Why do tutorial writers combine 10 technologies when 1 or 2 would do?

news.ycombinator.com

31–40 of 80 posts

Re: Ask HN: Why do tutorial writers combine 10 technologies when 1 or 2 would do?

#31

I'm dealing with this conundrum. I'm working on a Kubernetes course, and that's kind of pointless unless you deploy an app with containers. What app? I've settled on a smallish Rails app, though I realize many students won't be Rails developers. Additionally, I also realize many deploy targets for Kubernetes might be cloud specific (AWS, Digital Ocean, GCP, etc) Do I ignore those differences, or try to address those…

> I'm working on a Kubernetes course

Could be useful. Kubernetes is written in Go, so it fairly reasonable to expect them to have some clue with that language.

> I've settled on a smallish Rails app...

Huh? Well, I guess if your course is designed for people moving from Ruby to Go, then it'll be a good fit. For everyone else though, it sounds like you're adding a second language to the need-to-know list for prospective students. :(

Re: Ask HN: Why do tutorial writers combine 10 technologies when 1 or 2 would do?

#33

Yes not to mention git and docker are now assumed.

Those are pretty powerful ways to learn. With git, you can jump branches pretty easily as you proceed through the steps of a tutorial (either for the student or for the teacher to provide some assets for that step) Docker allows a packaged environment without having to install a bunch of dependencies, and easily shut down/remove those environments.

They are absolutely the most awesome things, and I couldn't go back to coding without Git and I am almost at that opinion with Docker. However as a beginner it must be daunting.

Re: Ask HN: Why do tutorial writers combine 10 technologies when 1 or 2 would do?

#35
I’d taught a programming class using Pascal one semester while in grad school so I felt well prepared to teach a workshop on the language to software developers from across my company the following year. I was wrong.

The students had differing levels of experience and different backgrounds, some COBOL programmers, some Fortran, some assembly language programmers. The company wanted to have the class taught over and over again to different groups, and I ended up teaching hundreds of programmers. What I realized was that it’s hard to anticipate everyone’s sticking points, and even when you think you know a subject, an unexpected question can be hard to answer clearly enough without boring some of the class.

Even simple ideas like scope rules for Pascal required several iteration before I had good examples to explain and motivate the rules. The workshops were so much better after my tenth time through the material. It’s not surprising to me that good tutorials take a lot of work and iteration to develop.

Re: Ask HN: Why do tutorial writers combine 10 technologies when 1 or 2 would do?

#36
post #4

Most tutorial writers are terrible at what they are trying to teach. They may have a vague grasp of a concept, but that's about as far as it goes. If they were more capable they wouldn't be writing tutorials. There are of course exceptions to this, but it covers at least 90% of the people who create courses for sites like Udemy. Comes back to the old saying, "Those who can, do. Those who can't, teach."

> Most tutorial writers are terrible

Not just writers, most tutorials are objectively terrible.

Trying to find a reasonable example on how to get something moderately complex off the ground is a humbling reminder of the Dunning-Kruger effect. The probability of an internet resource being highly ranked and visible has a near-linear correlation with the resource's unsuitability.

In fact, when it comes to technology, it appears to me that the most prominent authors are barely novices themselves. To make things worse, the instructions and "guidelines" they come up with are invariably as competent as encouraging to use SSL_NO_VERIFY flag because passing CA path is too difficult.

My mechanism for coping on the internet is simple: whenever I see a tutorial on anything non-trivial, I just assume it's been written on Sunday afternoon, after the author discovered the software on Friday night. These tutorials should be considered the modern-day equivalent of their author smiling from ear to ear and shouting "look ma, no hands!".

Which traditionally has been the augur of "look ma, no teef!"

Re: Ask HN: Why do tutorial writers combine 10 technologies when 1 or 2 would do?

#37
post #36
post #4

Most tutorial writers are terrible at what they are trying to teach. They may have a vague grasp of a concept, but that's about as far as it goes. If they were more capable they wouldn't be writing tutorials. There are of course exceptions to this, but it covers at least 90% of the people who create courses for sites like Udemy. Comes back to the old saying, "Those who can, do. Those who can't, teach."

> Most tutorial writers are terrible Not just writers, most tutorials are objectively terrible. Trying to find a reasonable example on how to get something moderately complex off the ground is a humbling reminder of the Dunning-Kruger effect. The probability of an internet resource being highly ranked and visible has a near-linear correlation with the resource's unsuitability. In fact, when it comes to technology, it…

Well you get what you pay for.

Re: Ask HN: Why do tutorial writers combine 10 technologies when 1 or 2 would do?

#38
post #35

I’d taught a programming class using Pascal one semester while in grad school so I felt well prepared to teach a workshop on the language to software developers from across my company the following year. I was wrong. The students had differing levels of experience and different backgrounds, some COBOL programmers, some Fortran, some assembly language programmers. The company wanted to have the class taught over and o…

This matters.

It may well be the tutorials are perfectly fine, depending on who you are.

I find that they way we organize and search for information through algorithms offered by the likes of Google and YouTube offer you this "10 sizes fit most" type philosophy where you get several results and they are deemed "the best" and you can self-select into using which tutorial is the most suitable for you. Though it may be the case that none of them are suitable for you, despite them being suitable for others.

Can you even conclude they are bad? I don't know.

I think there is a deeper lesson. It's not likely a situation arises that satisfies everyone and it's not likely you can tell when it is the situation that is bad or whether you are just not suited to it.

Re: Ask HN: Why do tutorial writers combine 10 technologies when 1 or 2 would do?

#39
I'm surprised at how negative a lot of people are around tutorial writers. In my (biased) experience, tutorial writers are

a) relatively good at what they do and what they're teaching, even if they're beginners and

b) definitely not driven by "showing off" or "building their CV" motivations.

Tech is hard. There is a lot of it out there. It's always changing. There are a lot of variables in terms of your set up and your needs. Maybe not every tutorial is going to solve your exact problem or remove all of your headaches, but imagine trying to work all of this stuff out without the amazing resource of records of other people trying stuff and taking time to explain.

Apparently back in the day, this was done over email and IRC. You would wait days to get an explanation from someone and some code to try out, and spend days hacking at stuff trying to figure it out for yourself.

Now you can find a tutorial that's specific to your needs and if you don't like it, you can read through 10-100 others.

Tech is hard, and tutorials aren't going to fix that. You'll still have to battle through your issues, alternating between emotions of "this is impossible. I'm not competent enough" and "OMG it works this is amazing". That's most of programming. If you don't like that experience, it's probably best to pick a slower moving field.

That's the "tech is hard" bit. Now writing. Writing is also hard. And because since school most people are put either into a "Arts" bucket or a "Science" bucket, very few people take time to figure out how sentence construction works and how to piece if statements together. It's quite admirable that people who have actively hated and avoided writing for most of their lives still see a gap and try to fill it by writing explanatory materials, usually for free.

And then there's education which is hard even if you're good at writing and good at technology. The curse of knowledge is a big hurdle. Finding the correct balance between maintaining a focus on one thing and giving enough context to that thing that you're explaining is hard.

So yes, I highly encourage everyone to get better at writing. Better at education. Better at technology. But to be good at all three is rare, and most of these people find they fit pretty well at universities as lecturers, where only a very limited number of students have access to them.

If you're keen to help fix the problem that you point out, add your voice. Spend some time writing a high quality tutorial after you find the solution to a problem that you're having. Find time to edit the tutorial for good flow, bugs, and everything else that makes a tutorial frustrating to follow.

I maintain a short list of technical writing and publishing resources [0], which I'd love to see more contributions to. I also write tutorials for CodeMentor [1], and a few other places[3]. Technical content is hugely valuable, so if you're interested in contributing, it's usually easy to find community editors at large sites who will give you free guidance and editing, and often even pay you for your content while letting you keep it under an open source license.

If you want help or advice on how to write, this is an open invitation to contact me through Twitter or Email and I'll happily look over your drafts, discuss outlines, or generally help you become a better writer.

[0] https://github.com/sixhobbits/technical-writing

[1] https://www.codementor.io/garethdwyer/posts

[2] https://dwyer.co.za/writing.html

Post reply on HN