6 ms·

People learn things differently. I really need the "core concept" first, before diving into examples, (unless the core concept is extremely simple). Many tuto

People learn things differently. I really need the "core concept" first, before diving into examples, (unless the core concept is extremely simple). Many tutorials are like hand-holding Lego building. Here's your Lego pieces, watch me and follow me in building this toy project, and you'll know how to Lego at the end of the day. I just don't function very well in this model. I want to know how and why decisions are made. I want to see things from the author's perspective. I want to know how the Lego pieces each feels like, and how they connect to each other, and how you arrive at certain designs in a certain way. Trying to follow tutorials before at least some high-level, conceptual discussion, feels to me like I'm trying to reverse-engineer something that I shouldn't need to. Most of the time if I'm approaching a new library or framework, I read read the introduction texts, and skip the "Getting started" code samples. Usually, there's going to be some sort of "Advanced" section where a lot more talking and discussing of concepts happens, and that's what I'd like to dive into first. I'll go for the API references next, try to grasp what the important interfaces look like, and finally I'll get back to the basic code samples in the beginning of the tutorial.

brugidou 2y ago
This may be a cultural trait too. Erin Meyer in her "Culture Map" Book mentions this idea that every culture approach persuading others differently from theory-first to examples-first.
rubslopes 2y ago
I agree. Many coding courses start with setting up your environment, where to download the base packages... I much prefer the core concepts first.
bbor 2y ago
Well put, you beat me to it! Specifically this line started my disbelief: Humans don't learn about things this way. Naturally, as is the hacker way, with no citations. I’ve only scratched the surface of pedagogy, but it’s a massive and mature academy drawing its modern principles from the empirical psychology of Dewey and Piaget. There’s a LOT more to say about it than can be covered in a blog post, much less a subsection of a blog post! As you point out, the biggest issue is that people are different. The next biggest issue is we aren’t even sure why those differences occur, or how stable they are over time… Well written post otherwise and it’s a good dive into the pragmatics of a particular educational strategy — I just would ask to see more humility, I guess!
bramblerose 2y ago
I have the same (and ran into this trying to wrap my head around why Maven didn't work... I don't want a tutorial explaining how to get started, I need to understand the fundamentals to understand what's happening!). I think, however, that starting from the examples might help with good API design: if you design your API to be "core concept first", this will likely lead to an API that _can only be used after you understand the core concepts_, which is not great when people are only occasional users.
hiAndrewQuinn 2y ago
I used to think I was a "core concept" kind of person, but later I realized I took that way too far and would refuse to do things outside of my comfort zone unless I felt like I truly understood everything ahead of time. Nowadays I'm much more likely to just jump in and start working with examples directly, and I feel much more productive. It's partly a thing of trust: I just trust that the makers of high quality software have put in enough thought to make their interfaces easy to understand, for the common use cases, without digging too deep into the internals. It frequently happens, of course, that I hit a roadblock where I do have to go deeper -- but that's only because there were 10 other things where I was successfully able to get by on surface impressions alone. So I find that even when I do dig in it's often time well spent.
- pc86 2y ago
  I would much rather have 60 different examples of middling quality covering a majority of use cases than a 5-page exposition about why the maintainer chose whatever database or why I should think of components as conveyer belts or whatever strained analogy they come up with. This only works with a lot of examples though, I've come across numerous projects where they think they're doing this but they've got a toy-level "Hello World" style example and maybe one more and that's it. But in a perfect world, they'd have both. The GP can read that essay and get their bearings, and I can click "Examples" and start copying & pasting until I start to figure out how things work.
  - rrr_oh_man 2y ago
    > why I should think of components as conveyer belts thanks for the chuckle!
fsndz 2y ago
how do you manage when the core concept are too abstract ? I guess then you would need some examples to understand ?
- powersnail 2y ago
  I’m generally okay with high level concepts talk, and don’t often find it too abstract. We are talking about documentations for libraries or frameworks after all. I’ll take a gentler approach if it’s an actual theoretical firld. Obviously, during the first read, my understanding of those concepts would be full of holes. And I plug them as I continue reading the API references and later when I start to try it hands-on.
myworkinisgood 2y ago
That's why there are four axes of documentation.
- gomerspiles 2y ago
  Sounds like you have an explanation of how painful documentation is.. But how do these axes work?
  - wmanley 2y ago
    Possibly the gp means the four quadrants (two axes)?: https://dunnhq.com/posts/2023/documentation-quadrants/ https://dunnhq.com/posts/2023/documentation-quadrants/
  - fragmede 2y ago
    > There are 4 types of documentation, laid out on two axis: > Learning vs. Doing > Practical vs. Theoretical -tutorials -how-to guides -discussions -reference https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/
kccqzy 2y ago
I cannot agree more. I also want to add that I hate these "project generators" such as create-react-app when I'm just getting started. (It's just an example: I'm glad I learned React long before its existence.) They create an opinionated folder structure with template files and preconfigured tools. I don't function well in this model: if I don't immediately have a high-level overview of what the created files do, why they are created this way, I just become uneasy at all this magic that I do not understand. Each time a new thing is introduced, I need a high-level introduction covering its purpose that relates to the concepts I already know. I'm not comfortable dealing with magical black boxes unless I have at least a rudimentary understanding of the main interface of that black box. To put this back into the concrete example, it means that hypothetically if I were to be learning create-react-app from scratch, I would immediately begin to investigate the purposes of the tools that have been configured by it, like Babel and ESLint.
- LoganDark 2y ago
  I think this way too and I think it's because I'm autistic. I don't WANT to clone a project in one click. I want to understand every tool well enough to create my OWN project that serves MY use cases.
- wiseowise 2y ago
  I absolutely loathe those “frameworks“ with billion files in billion directories. If can't start with single file and build upon it - it is complete trash. Android projects with Gradle come to mind.
  - vbezhenar 2y ago
    I'm doing the following approach: 1. Create new project. 2. Carefully inspect every file in the project. Remove everything non-essential from every file. 3. Repeat step 2, until things just don't work and find out why they don't work. After that work is done, you'll be with few files which are somewhat easier to understand than the original state. On my experience, people who create tools, usually have good built-in defaults, so you can actually delete almost everything.
ChrisMarshallNY 2y ago
I write very verbose tutorials ([0] has my latest effort). I walk through the reasoning, from start to finish, and usually use things like Git tags and releases, to support the prose. I also like to provide examples that are very “real-world.” It doesn’t seem that people read it. I think folks prefer videos and unrealistically sparse examples. [0] https://littlegreenviper.com/series/universal-links/ https://littlegreenviper.com/series/universal-links/
k__ 2y ago
Tried that and don't know how I successfully studied computer science that way. I could reproduce solutions, but I never understood them. Years after I saw a bunch of good practicable examples and I just understood what the concept was about. After this realization, I refined my learning approach. 1. Fly over the core concepts. 2. Try a bunch of examples until I understand why I would need the concept. 3. Read the core concept thoroughly to eliminate the edge cases that are missing in the naive examples.
directevolve 2y ago
Yeah, I don't know why this post is so either/or. Why not both? I like projects that have docs with core concepts in one section, examples in another. Or where the core concepts give working examples as code snippets.
valval 2y ago
All coding tutorials I’ve come across struggle with this. I couldn’t care less about some scripted video building a trivial piece of software, even if it’s pretty close to what I was going to build. The optimal coding tutorial in my eyes would just be a day in the life of a software engineer building something new and thinking out loud. Of course that wouldn’t do well in video format. I think this is just the tech equivalent of teach a man to fish instead of yada yada.

brugidou 2y ago

This may be a cultural trait too. Erin Meyer in her "Culture Map" Book mentions this idea that every culture approach persuading others differently from theory-first to examples-first.

rubslopes 2y ago

I agree. Many coding courses start with setting up your environment, where to download the base packages... I much prefer the core concepts first.

bbor 2y ago

Well put, you beat me to it! Specifically this line started my disbelief: Humans don't learn about things this way. Naturally, as is the hacker way, with no citations. I’ve only scratched the surface of pedagogy, but it’s a massive and mature academy drawing its modern principles from the empirical psychology of Dewey and Piaget. There’s a LOT more to say about it than can be covered in a blog post, much less a subsection of a blog post! As you point out, the biggest issue is that people are different. The next biggest issue is we aren’t even sure why those differences occur, or how stable they are over time… Well written post otherwise and it’s a good dive into the pragmatics of a particular educational strategy — I just would ask to see more humility, I guess!

bramblerose 2y ago

I have the same (and ran into this trying to wrap my head around why Maven didn't work... I don't want a tutorial explaining how to get started, I need to understand the fundamentals to understand what's happening!). I think, however, that starting from the examples might help with good API design: if you design your API to be "core concept first", this will likely lead to an API that _can only be used after you understand the core concepts_, which is not great when people are only occasional users.

hiAndrewQuinn 2y ago

I used to think I was a "core concept" kind of person, but later I realized I took that way too far and would refuse to do things outside of my comfort zone unless I felt like I truly understood everything ahead of time. Nowadays I'm much more likely to just jump in and start working with examples directly, and I feel much more productive. It's partly a thing of trust: I just trust that the makers of high quality software have put in enough thought to make their interfaces easy to understand, for the common use cases, without digging too deep into the internals. It frequently happens, of course, that I hit a roadblock where I do have to go deeper -- but that's only because there were 10 other things where I was successfully able to get by on surface impressions alone. So I find that even when I do dig in it's often time well spent.

pc86 2y ago
I would much rather have 60 different examples of middling quality covering a majority of use cases than a 5-page exposition about why the maintainer chose whatever database or why I should think of components as conveyer belts or whatever strained analogy they come up with. This only works with a lot of examples though, I've come across numerous projects where they think they're doing this but they've got a toy-level "Hello World" style example and maybe one more and that's it. But in a perfect world, they'd have both. The GP can read that essay and get their bearings, and I can click "Examples" and start copying & pasting until I start to figure out how things work.
- rrr_oh_man 2y ago
  > why I should think of components as conveyer belts thanks for the chuckle!

fsndz 2y ago

how do you manage when the core concept are too abstract ? I guess then you would need some examples to understand ?

powersnail 2y ago
I’m generally okay with high level concepts talk, and don’t often find it too abstract. We are talking about documentations for libraries or frameworks after all. I’ll take a gentler approach if it’s an actual theoretical firld. Obviously, during the first read, my understanding of those concepts would be full of holes. And I plug them as I continue reading the API references and later when I start to try it hands-on.

myworkinisgood 2y ago

That's why there are four axes of documentation.

gomerspiles 2y ago
Sounds like you have an explanation of how painful documentation is.. But how do these axes work?
- wmanley 2y ago
  Possibly the gp means the four quadrants (two axes)?: https://dunnhq.com/posts/2023/documentation-quadrants/ https://dunnhq.com/posts/2023/documentation-quadrants/
- fragmede 2y ago
  > There are 4 types of documentation, laid out on two axis: > Learning vs. Doing > Practical vs. Theoretical -tutorials -how-to guides -discussions -reference https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/

kccqzy 2y ago

I cannot agree more. I also want to add that I hate these "project generators" such as create-react-app when I'm just getting started. (It's just an example: I'm glad I learned React long before its existence.) They create an opinionated folder structure with template files and preconfigured tools. I don't function well in this model: if I don't immediately have a high-level overview of what the created files do, why they are created this way, I just become uneasy at all this magic that I do not understand. Each time a new thing is introduced, I need a high-level introduction covering its purpose that relates to the concepts I already know. I'm not comfortable dealing with magical black boxes unless I have at least a rudimentary understanding of the main interface of that black box. To put this back into the concrete example, it means that hypothetically if I were to be learning create-react-app from scratch, I would immediately begin to investigate the purposes of the tools that have been configured by it, like Babel and ESLint.

LoganDark 2y ago
I think this way too and I think it's because I'm autistic. I don't WANT to clone a project in one click. I want to understand every tool well enough to create my OWN project that serves MY use cases.
wiseowise 2y ago
I absolutely loathe those “frameworks“ with billion files in billion directories. If can't start with single file and build upon it - it is complete trash. Android projects with Gradle come to mind.
- vbezhenar 2y ago
  I'm doing the following approach: 1. Create new project. 2. Carefully inspect every file in the project. Remove everything non-essential from every file. 3. Repeat step 2, until things just don't work and find out why they don't work. After that work is done, you'll be with few files which are somewhat easier to understand than the original state. On my experience, people who create tools, usually have good built-in defaults, so you can actually delete almost everything.

ChrisMarshallNY 2y ago

I write very verbose tutorials ([0] has my latest effort). I walk through the reasoning, from start to finish, and usually use things like Git tags and releases, to support the prose. I also like to provide examples that are very “real-world.” It doesn’t seem that people read it. I think folks prefer videos and unrealistically sparse examples. [0] https://littlegreenviper.com/series/universal-links/ https://littlegreenviper.com/series/universal-links/

k__ 2y ago

Tried that and don't know how I successfully studied computer science that way. I could reproduce solutions, but I never understood them. Years after I saw a bunch of good practicable examples and I just understood what the concept was about. After this realization, I refined my learning approach. 1. Fly over the core concepts. 2. Try a bunch of examples until I understand why I would need the concept. 3. Read the core concept thoroughly to eliminate the edge cases that are missing in the naive examples.

directevolve 2y ago

Yeah, I don't know why this post is so either/or. Why not both? I like projects that have docs with core concepts in one section, examples in another. Or where the core concepts give working examples as code snippets.

valval 2y ago

All coding tutorials I’ve come across struggle with this. I couldn’t care less about some scripted video building a trivial piece of software, even if it’s pretty close to what I was going to build. The optimal coding tutorial in my eyes would just be a day in the life of a software engineer building something new and thinking out loud. Of course that wouldn’t do well in video format. I think this is just the tech equivalent of teach a man to fish instead of yada yada.