'Read the Docs' and Escalation of Complexity.

This is going to be a bit of a rant. But I think that, at the very least, it will help me organize a few thoughts about what it is like to teach myself to code. In the best case scenario, possibly I can point out a few things that will help more experienced coders share their knowledge. If I could choose my own target audience, it would be anyone creating educational coding content, regularly providing answers on forums like stackoverflow or r/learnprogramming, and/or making courses for youtube, udacity, udemy, etc.

Since I'm the newb in this situation, why would I be providing advice at all? For one simple reason: The Curse of Knowledge.

It is extremely apparent that many well-intentioned instructors have great difficulty in remembering back to a decade before when they didn't know what they know now. They can't put themselves in the shoes of a student who hasn't had the time and experience to build up a rich vocabulary of jargon, topical connections, and analogies. This leads to some grave errors, both in tutorials and in answers to questions on forums.

All that being said, I'll just break down my gripes into two sections:

1. "Read the Docs."

There is no single cliched phrase that makes me feel so bewildered and inadequate as this one. Sometimes, saying 'Read the Docs," is just an obvious cop out, motivated by laziness. I'd hazard a guess that 70% of the time this phrase appears on forums it fits into this category, written by someone that wishes to appear knowledgeable while also remaining either incapable or unwilling to productively share what they claim to have mastered. Such is the self-aggrandizing behavior of nerds on the internet, and it is commonplace and not particularly surprising.

But I don't want to get too far into the weeds with that group; it isn't worth worrying about bad actors. What really confuses me is how so many otherwise competent instructors seem to think that this is genuinely relevant advice.

I can read the docs on a JS method or a CSS trick, and I can apply that information. But right now I'm working on a fullstack application using SQLAlchemy and Flask and Postgresql. Have you seen the docs for those tools? There are dozens to hundreds of links, each referencing different tools that are completely unprecedented to a coding student, and each link opens up to an article that can only be parsed by someone who already understands another set of jargon. This is a rabbit hole at best and a paradox at worst.

I get that there are some savants out there who are much more clever than I am, who don't use tutorials, and who get started by reading docs and building a project without any hand-holding. But I would think it would be apparent that such outliers are emphatically not the core audience for tutorials and courses.

If you are introducing me to SQLAlchemy, what possible use could it serve to invite me to 'Read the docs?' Which docs? All of them at once? That would be like inviting me to quit your course to read a short to medium length novel full of foreign language terms that I would be forced to look up just to make it through a few sentences. It isn't an exaggeration in any sense to say that I could start on one set of docs and study them and their jargon and the jargon used to define those terms indefinitely. If I intended on actually remembering anything that I'd read, I'd have to also write notes and build small projects with all of those new methods and parameters, and as I am currently incapable of building those projects I would have to find another tutorial to guide me through the process, spinning my wheels in tutorial purgatory.

I've spent 41.5 hours in the last week on a Udacity course. It has taken me that long to go through the material, work on the projects, debug, read and watch other resources to supplement what I can't understand from the course. In what way could it possibly make sense to also follow the instructor's advice to 'Read the docs' for half a dozen complicated tools? How would I ever make progress in that way? Can Achilles catch the tortoise if every step forward requires infinite intermediary steps?

2. Escalation of Complexity.

This is my own term for a phenomenon that might already have a name in learning theory. What I mean is the difficulty of tests, questions, or projects as compared to the preceding educational material.

There is nothing as demoralizing to a student of coding as reading a page explaining a single concept, and then being asked to prove their comprehension by answering a question that escalates the complexity beyond recognition.

For example, let's imagine I wrote a chapter about creating variables in JS, and gave examples of using const or let followed by a name, equals sign, and value. Now it is time to test the student. What problem should I give them to work out?

1. Arrange the following into the correct syntax to declare a variable:

[myVar, =, "Hello, World", const]

or, instead, should I ask

2. Write an algorithm that demonstrates the differences in scope between var, let, and const.

That is a clumsy example, and contrived, but hopefully it at least communicates how it feels for a student to learn how to count to 10, and be tested with a question requiring them to count to 100. The first question could be described as a "1" on a scale of complexity, as it mirrors the content without any twists, and could possibly be answered by an attentive reader who is good at tests but not actually learning code. The second question, however, might earn a score of "20" or more in terms of escalation, and any student who could answer it would prove themselves overqualified for such a course in the first place.

For a more real world example, let me try to describe my experience with my current Udacity course, and to list some examples of the complexity that is introduced in the first unguided project, as compared to the project that we built along with the chapter material.

The first real project introduce and requires...

• The use of virtual environments, while providing a single set of instructions that assume operating system and don't bother explaining that they are not universal
• 3 or more tables for the DB, each with 10 or more columns of information to keep track of, as compared to 1 table with 2 columns in the walkthrough project.
• The use of template inheritance
• The use of Bootstrap
• A project scaled at over 10 html pages, 6 individual forms, a separate config file, as compared to a walkthrough project with one of each
• Greater variation and complexity in the employment of fetch(), using json, and all the other topics introduced in the material

I am absolutely not suggesting that a good teacher should never challenge their students with a moderate escalation of complexity. I am absolutely not suggesting that struggle is bad, or that the most important lessons aren't learned by doing rather than passively watching/reading.

What I am saying is that any high quality instructor, in code or any other subject, should constantly be aware of the complexity of the problems they use to test their students knowledge, and should be intentionally manipulating that complexity. A good teacher should be able to articulate why one project is appropriate based on what it requires, and why a slightly more or less complex project would be unsuitable.

Conclusion:

I have am extremely lucky to have access to endless free and paid learning resources to help me transition into a new career. I take responsibility for my own progress in this pursuit, and recognize that it is limited by my intelligence, dedication, consistency, study habits, lifestyle choices, and so on.

If you answer questions on forums because you have a sincere desire to share what you've learned, or if you produce educational content and want to provide a high quality service that will earn you more clicks, likes, ad revenue or tuition fees, please reconsider both the generic advice for beginners to "Read the docs" and the escalation of complexity in your material. Ask yourself:

If a student is learning to use _____ technology for the first time, what are the chances they will be able to grok the full documentation for that tech?

Am I advising someone to 'Read the docs," in good faith, perhaps with a link to the relevant page that a beginner might not have found on their own? Or am I saying it to save myself time?

Is it possible that I am subject to a Curse of Knowledge bias, and am unable to imagine that a beginner would not be able to form the proper google search keywords to find the answer to their question?

Am I asking a student to answer a question that does not escalate complexity, escalates the complexity to a point that will require them to think, to a point that will inevitably frustrate them, or somewhere in between?

How can I be aware of the complexity of tests and projects in my course, scale it, and intentionally apply it, while avoiding the temptation to mistake an expert's grasp of a subject with a beginner's?