General > General Technical Chat
How tutorials confuse people
(1/2) > >>
eti:
How programming tutorial authors brains appear to work:

Let’s say I only speak English, and I consider X programming language as “Russian” to me.
I see some code on a forum or blog, knowing that I need to apply this code one-off to fix something, often a CONSUMER device and I don’t really want to take a masters in programming - I merely want to know what this does, so I’m self-sufficient next time - maybe a simple one liner to get my phone out of a boot loop etc.

So I ask whomever wrote the “tutorial” (and I use that word extremely loosely, based on what we find online) to give me a clear, simple translation from “Russian” into English… but what usually happens, instead, is that they translate it from “Russian” into another, rather obscure, rural variant of “Russian” BUT STILL NOT INTO ENGLISH AS ASKED FOR.

Why is this so prevalent? Assumptions are usually made of the reader. In my experience:

“Assume makes an ASS of U and ME”

ataradov:
Because when writing a tutorial you need to assume some level of the reader. That's why there are basic and advanced tutorials. Otherwise there will never be any advanced tutorials that are not full on books.

You failing to find a needed tutorial or not having the skill to understand the existing one is not the fault of the writers of the tutorials.

In fact, I have the reverse issue with reading scientific papers, especially PhDs. You have to skip 20 pages of history of the subject and other works. If I'm reading your PhD, I expect to know the history of the subject. I understand that they need the pages to pad the work, I did the same for my diploma. But my diploma would not be of any interest to anyone. I really wish that it was more acceptable to just defend a 10- or 20 page thesis that is just the new stuff.
Rick Law:

--- Quote from: eti on May 15, 2021, 04:36:08 am ---How programming tutorial authors brains appear to work:

Let’s say I only speak English, and I consider X programming language as “Russian” to me.
I see some code on a forum or blog, knowing that I need to apply this code one-off to fix something, often a CONSUMER device and I don’t really want to take a masters in programming - I merely want to know what this does, so I’m self-sufficient next time - maybe a simple one liner to get my phone out of a boot loop etc.

So I ask whomever wrote the “tutorial” (and I use that word extremely loosely, based on what we find online) to give me a clear, simple translation from “Russian” into English… but what usually happens, instead, is that they translate it from “Russian” into another, rather obscure, rural variant of “Russian” BUT STILL NOT INTO ENGLISH AS ASKED FOR.

Why is this so prevalent? Assumptions are usually made of the reader. In my experience:

“Assume makes an ASS of U and ME”

--- End quote ---

First, why "assumptions":

Do writings, like making a movie, are done for a target audience.  The authors (movie-makers) either do a detail survey of the audience by asking a whole bunch of questions first, or the authors (movie-makers) select a target and write accordingly.  If you don't like Sci-Fi, don't go see "Aliens", it wasn't made for you.  The box-office will determine whether the movie-maker's selected target is good or bad.

Second, the lack of simplicity:

Programming is easy when you are doing simple things.  But simplicity is often just surface deep.  "Colonize Mars" is simple to say, but "details" is what makes it complex.  Regardless of what simple thing it does, the process of getting the CPU to do that may be extremely complex.

Some codes are easy, but some codes are hard.  That is why in the profession of software development, you have some making a few hundred dollars a week, and some making a few hundred dollars an hour; commensurate with the level of knowledge required and complexity.

In many cases, making "tutorial" easy to understand may not be achievable.

Learning is hard work.  Granted, some complex writings are bad, but some complex writings are necessary even if it in "obscure, rural variant" form.   You can't skip the understanding of the important stuff yet achieve the general understanding "for next time".

jfiresto:

--- Quote from: ataradov on May 15, 2021, 04:47:36 am ---... In fact, I have the reverse issue with reading scientific papers, especially PhDs. You have to skip 20 pages of history of the subject and other works. If I'm reading your PhD, I expect to know the history of the subject. I understand that they need the pages to pad the work, I did the same for my diploma. But my diploma would not be of any interest to anyone. I really wish that it was more acceptable to just defend a 10- or 20 page thesis that is just the new stuff.

--- End quote ---

I tend to the notion that you are much more into development than research, as this completely misses the point of the opening literature review. I will try to state its purpose in engineering terms. The review tries to enumerate the work's common, background assumptions in testable form. If and where the work fails – and it is prudent to assume when, not if, if the work is new and original – the review provides an audit trail to trace back a failure to its false or misleading assumptions.
ucanel:
Are that tutorials free of charge?
Navigation
Message Index
Next page
There was an error while thanking
Thanking...

Go to full version
Powered by SMFPacks Advanced Attachments Uploader Mod