How tutorials confuse people

[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]

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”

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]

... 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.

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?

[JohnnyMalaria]

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.

I cannot agree with this. A thesis is more than just a write-up of something new. It is a self-contained document of a theory and the attempts to validate or disprove it. In writing it, you have to lay out your argument, so the history is necessary. Not only is it necessary for the reader, but also for the writer (in the case of a document submitted for a degree) to demonstrate to the examiners that the writer understands the subject. One of my examiners challenged the opening sentence in my introduction! I've read too many papers (and some theses) where the author clearly misunderstood the subject. It is becoming more prevalent with newer generations of researchers. I now use the quality of the write-up of the history to gauge the credibility of the paper.

Also, when I read someone else's thesis, I do not necessarily know the history and I need that background information to understand the subject matter overall and what is novel about the author's work.

If you don't want to read the introduction/history etc, just skip it. It's easy enough.

[DrG]

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.

I think some terminology needs to be specified a little more carefully...

In an academic sense a "thesis" is associated with one of the requirements for a masters degree. A dissertation is associated with one of the requirements for a PhD. EDIT: This distinction may be more country-specific than I knew when I wrote that line, although I think it holds pretty well in the US academic world.

A "scientific paper" is a much looser term, but in a pure form, it is a paper published under peer review in the "scientific literature" and the terms "scientific paper" and "scientific literature" have increasingly less specific meanings.

Normally, you should never see a 20 page "history" in the scientific literature because journals have page limits. You always see a "background" section to set the context of the study and it should include key finding from previous reports that are relevant to the current report.

You should always see a 20 page history" in a dissertation because the idea is that the author knows everything that has been published in some specific, and usually, very narrow field. That section always needs to be there because it is a requirement that you demonstrate that you, in fact, do know everything about some specific areas that came before you. The academic concept, for better or worse, is that you need to know everything about the "subject" before you can add to the "subject".

[JohnnyMalaria]

In an academic sense a "thesis" is associated with one of the requirements for a masters degree. A dissertation is associated with one of the requirements for a PhD.

I think this is country-specific. I wrote a PhD thesis, not a dissertation.

[DrG]

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”

It is so prevalent because "tutorials", like you are describing them (i.e., online tutorials) do not, necessarily, earn much cash for the author. In fact, many appear as a result of "paying" the author NOT in cash but rather in "notoriety". The scheme here seems to be that if you get enough notoriety points, you can earn influence points and if you have enough of those, you can say that you are an "influencer" and you will get millions of YouTube hits and make lots of cash. No degrees necessary.

The whole concept has resulted in a lot of low quality content, because, apparently, some content is better than no content, for the ability of a site to support advertising that keeps them afloat.

On the other hand, YOU get to decide whether the tutorials are quality pieces of "subject matter expertise" writing. Since these are, by definition, "how to" guides, you may not be able to make the evaluation before the time investment, but it is a low cost investment and with time and experience, most of us develop an intuitive sense about how well written they are before investing in the time to use them.

Take for example, this tutorial (which I have linked here before) https://www.howtogeek.com/129728/how-to-access-the-developer-options-menu-and-enable-usb-debugging-on-android-4.2/

It is a straightforward tutorial on how to get to developer options on an android device. It is, IMO, very well written and illustrated. It does this one thing very well. I probably looked at several on this subject before seeing this one and now I know how to so this one thing. Successful tutorial.

There used to be a proliferation of "for dummies", "idiots guide" and the less offensive "24 hour" guides. These could be just fine if you have very little experience with that particular area. When they were books, they had, at least, some quality control and they were intended to be purchased for $$$. Today's tutorials, as I said, have no such encumbrance.

When you get into more detailed areas (e.g., PIC32 devices) you find fewer tutorials because there are fewer people with the knowledge and experience to write them for "free". Edit: Instead, I start searching for Design Notes or Application notes - but they are not tutorials.

But if you want to flash an LED on a microcontroller (and many of us did experience a time when we did not know how to do that), there are plenty.

That is how I see it anyways.

[DrG]

In an academic sense a "thesis" is associated with one of the requirements for a masters degree. A dissertation is associated with one of the requirements for a PhD.

I think this is country-specific. I wrote a PhD thesis, not a dissertation.

(Attachment Link)

Yeah, I think you are probably right. For me, the dissertation was always for the PhD and the thesis for the Masters. But, as you say, this may be country specific - https://www.enago.com/academy/thesis-vs-dissertation/ and it is the case that in some areas, a thesis is written for a PhD - I edited my post, thanks.