Why Don’t Developers Like Documentation? | DevRel University
We take learnings from cognitive scientist Daniel T. Willingham’s Why Don’t Students Like School and apply them to teaching developers. We use this book to understand how people learn and how we can use that to our advantage as educators. In essence, we answer “how to learn how to learn.”
Introduction
Many of us know there are three kinds of learners:
- Visual: People who learn best by visible stimuli like graphs and pictures
- Auditory: People who learn best by listening to stimuli like audiobooks
- Kinesthetic: People who learn best by doing hands-on practice
When you understand this, you can create content that targets a student based on which one of these three they are categorized.
This is something that many teachers and learners know, and they use to create curriculum and content. Unfortunately, “there are three kinds of learners” is completely and utterly false.
Even our precious ChatGPT gets this wrong.
Sorry to have to pull a fast one on you.
I did this, however, to show you that there are a lot of incorrect preconceived notions about how people learn best. As developer advocates and educators, when was the last time you asked:
“How do developers/security researchers learn?”
“How can create content to teach developers that actually sticks?”
If you’ve never asked this question, this article will be your foray into how anyone learns and how we can use this knowledge to improve ourselves and our developers. These are some tactics I’ve used over the last four years of making smart contract security researchers and developers educational content and videos.
If you don’t believe me, that’s fine. We will use the teachings from Harvard-educated, professor of psychology at the University of Virginia, Daniel T. Willingham’s book, Why Don’t Students Like School, which should be required for anyone in the developer relations career. In his books, he gives exact studies conducted to conclude much of what we will suggest here. For those looking for specific studies, please consult the bibliography of his book.
Learning how to learn
So, let’s answer the question, “How do developers learn?” so as developer educators, we can learn how to teach developers more effectively. Or, as developers ourselves, we can learn how to learn faster and more efficiently.
Summary at the bottom
At the bottom of this article, I have a list of quick tips to remember when creating developer content. You can think of it as the summary of this article.
How does the brain/memory work?
To get started, let’s first focus on how we store information in our brains. Once we understand how information is stored, we can use this to optimize the process.
To start, we can think of thinking as having three separate components:
- Environment
- Working Memory
- Long-Term Memory
As developers, our brains work quite analogous to how computers work! If you treat your brain like a computer, it works in much the same way.
- Operating System Inputs/Outputs
- RAM / Computer Memory
- Storage (SSD, HDD, Thumb drive, etc)
And the " thinking " process works much of how we’d expect. As we concentrate on things and solve problems while actively working on them, they stay in our “working” memory, our short-term minds. The longer we think about them and keep them in our working memory, the more they are stored in our “long-term” memory.
Information stored in our long-term memory can be recalled or brought out of storage without looking it up. There are a lot of skills/information that we want to place in long-term memory:
- When should we write tests?
- What is fuzzing?
- What types does this language support?
The more information we have in our long-term storage, the easier it is for developers to get work done since they will be able to just “code” without having to Google or ask ChatGPT, and more importantly, the easier they will be able to recognize when an AI friend gives us bad information.
We can go one step further with our analogy for us smart contract/EVM folks here, with calldata, memory, and storage.
The process of learning is when we effectively store information (be it procedural, factual, etc) in our long-term memory.
How do we get information into our long-term memory?
Here is one of the most important concepts for you to know as an educator:
Memory is the residue of thought
The longer you keep information in working memory, the longer you actively mentally work on something, the more of that information will get stored in long-term memory. This seems somewhat obvious in hindsight, as we’ve heard the age-old adage: “Practice makes perfect.”
So, as educators, we want to get our students thinking a lot about a topic.
Tip: Get developers thinking about your topic a lot
…But how do we do that?
How do we get developers thinking? | Curiosity
If you’ve ever sat on a bus, plane, or train and looked out the window, you’ve probably found it pretty easy for your mind to drift, and you to wonder.
- Ooh, look at that tree. I wonder how it got there.
- The breakfast I had this morning was so good, I wonder if I’ll have it again tomorrow.
- If I tilt my head, I can line up the spots on the window with my double-vision
You’d find it much harder for your mind to naturally start doing calculus or finding integrals in your head. Intense thinking is difficult, whereas curiosity and asking questions come more naturally. Most of us know this, but most don’t use it to empower our learning.
This brings us to our next point in creating developer content:
Tip: Focus content on asking questions, and making “the thing to learn” the answer to that question.
Additionally, we can apply this to make ourselves learn better:
When learning, try to frame all learnings as a question. “What question am I answering with this knowledge?”
We should use our natural curiosity to our advantage, and focus on creating questions to tap into that curiosity.
What are developers curious about?
People however, are curious about different things. The above image shows two kinds of problems, and if both are shown to groups of people, they will be more likely to pick the sudoku problem than the algebra problem.
Why?
There are a couple things to keep in mind when it comes to curiousity:
- Difficulty
- Coolness/Content
We’ll discuss difficulty in it’s own section of this article.
How do we get developers thinking? | Content
Developers are people. People like “cool stuff”. If you asked a developer if they wanted to make an AI to predict Owl hunting patterns, it would matter a lot on how much that developer cared about Owl hunting patterns and AI for them to be interested.
Developers get uninterested if the content is “lame”. A lot of people look at developers as “lovers of dry boring stuff”. This is far from the truth. Some developers do, but even the ones who love “dry boring stuff” love a deep dive into a technical topic, so even they have content they think is “cool” and content they think is “lame”. This brings us to two tips:
Tip: Make cool content
Note, this doesn’t mean you have to make “relevant” content, you’ll want to make content relevant where it makes sense. It can be very difficult to make content relevant to everyone in your target audience, and even when you find common ground, you don’t want to force an analogy to work.
For example, above I gave an analogy about how the mind works compared to the EVM, by doing so, I’ve cut down on the amount of people this article will be helpful for.
And this leads us to our most important tip:
Tip: Know your students
- Know their starting background knowledge
- Anticipate their pitfalls
- Know what they think is “cool”
This tip could be the summary of the whole article. Writing and teaching could be summarized to “anticipating the pitfalls of students while trying to master a skill.” We’ll go over this tip more later in this article.
Web3 DevRel Examples of peeking curiousity:
- How does MetaMask connect to my Website? -> Tutorial on building a Web3-compatible app
- How was the Vyper compiler a victim of a $75M hack? -> Tutorial on how Vyper has in-language reentrancy locks
- How can Aave offer a 7% interest rate on USDC? -> Tutorial on how lending and borrowing pools work
How do we get developers thinking? | Difficulty & Mind Maps
Difficulty
As we’ve expressed, difficulty is one of the things that can help/discourage someone from getting curious about something. If a topic is too easy, a developer won’t get the hit of dopamine when they solve the problem. If the topic is too hard, they also won’t get the hit of dopamine since they won’t solve the problem, and working on it will get frustrating. So to do this, you’ll always want to make the topic you want to teach just slightly harder than the student’s current level.
Tip: Make content just slightly harder than the student’s current level
What makes a subject difficult?
There are a few factores when it comes to difficulty that we will dicuss in this article.
- Not enough background knowledge
- Not enough knowledge overall
- Slow learning ability
Let’s discuss.
What makes a subject difficult | Not enough background knowledge
When a student doesn’t have prerequistie knowledge on a subject, you’re pretty much dead in the water right there. Learning new knowledge is often more simply the process of anchoring the knowledge to something else already hammered into long-term memory.
Tip: Understanding Is Remembering in Disguise
Often, when students first learn something, they add the new knowledge into their already held notions about the world.
This is often why it can be so jarring to learn something you thought to be previously true is false. You may have built up an entire understanding of the universe from that fact. Imagine if I told you today “Scientists have concluded that Humans actually breathe Uranium instead of Oxygen” — you’d fall into a state of disbelief of everything and have to undergo a long difficult effort of having to re-learn how the human respiration system works.
This “mind map” that we create of the universe is what also what makes diagrams so helpful, they visibly show us what that “mind-map” looks like.
So a topic can be difficult if there isn’t enough information about the universe for the new knowledge to latch on to.
Tip: Know EXACTLY how much knowledge your students have prior to reading your content. If they may not have the required prerequisites, make that content
What makes a subject difficult | Not enough knowledge overall
What if I told you, that the more you know, the easier it is to know?
Sounds weird doesn’t it?
A study was done where statistically “good readers” were compared against “poor readers” were told to read text about baseball. They were additionally sorted by their level of knowledge about baseball. What the study found was that poorer readers scored higher on reading comprehension when they had more background knowledge about a topic.
This lead scientists to believe that having more knowledge around a topic makes learning easier.
One of the questions I get asked a lot is “Should I learn Solidity, Vyper, or Rust?” and my answer is some derivative of “Learning one will help you with the other down the line. If you’re nervous about picking the right one, don’t be! Learning one will make learning the other much easier.”
Seasoned veterans reading this will likely understand this. Your first programming language was likely quite challenging to master. But as you became better, other languages started becoming easier as well. Your understanding of languages in general got better, and you started noticing what to look out for.
Tip: Know your students
We are starting to see why “Knowing your students/target audience” is so important.
What makes a subject difficult | Slow Learning Ability
Sometimes, some learners are just going to be slower than others, but studies have shown that this can be improved with hard work. Studies have been done to see what plays a more important role:
- Genetics
- Hard work
The results have been very interesting, and a mix of the two is the ultimate outcome, but they have proved that environment can play a critical role. If you’re interested in diving more into this, check out the Flynn effect. These studies have shown that yes, genetics play a role, but hard work can massivly improve someone’s intelligence and ability.
However, if someone thinks they can’t get smarter, they might just be discouraged from the get-go. A book called Mindset by Psychology PhD Carol S. Dweck focused on how important the belief someone has in themselves is to how much they can grow.
Students in studies who think knowledge is malleable often push harder and go the extra mile to learn something, resulting in them doing better, while those without that mentality, don’t.
The most important take aways from this are:
Tip: Never praise “ability”, always effort
Someone can always imporve their ability by continuous effort. Be sure not to always say “nice job champ” regardless of outcome, you want to praise effort and push students towards better outcomes, otherwise students may start to think outcomes are not important.
Tip: Make sure students know that hard work pays off, and their intelligence can be improved
And finally:
Tip: Treat failure as a natural part of growth
If you never hit a wall, you’ll never know your limits. When you do hit walls, most of the growth will be in learning to overcome the obstacles.
How to get developers thinking? | Reward
Curiosity is fragile, especially because as we’ve stated, active thinking is difficult. Studies have shown that actively solving problems (by thinking) sends dopamine signals to your brain, as a sort of reward, but solving a problem for problem-solving itself might not be enough.
An important concept for educators is to keep at the front of the learners mind why they should keep learning. Why they are on the journey. We need to make sure our students know exactly what benefit they are going to get out of aquiring the knowledge they are going to work to aquire.
As learners we can use this as well, if we focus on the reward we will get when we finish learning, we will more likely finish actually learning this. This is why, in Cyfrin Updraft, we dedicate time to students writing down why they want to learn a subject. This makes it so in those moments when things get hard, when thinking becomes tiersome, they can fall back on that reward they are going to get from learning the subject.
Some examples may be:
- A new career
- Better paycheck
- Build a innovative tool
- etc
Tip: Keep the reward at the forefront of students minds
“Learn to Earn” type programs can be dangerous
It’s important to be careful about how you do this part though. Some projects approach this with a more direct “learn to earn” approach, where they offer monetary rewards in return for learnings. This can backfire, and students learn just enough to claim the reward without actually learning the desiered information.
So when using rewards, be sure this is done carefully. A much better methodology is to remind students what abilities they will be able to have/do after they learn the information.
How to get developers thinking? | Drills
Now, the most effective way to get someone to get a subject into their long-term storage is to run drills/consistently practice. This makes sense, as the way data is placed into long term storage is based on how long it’s been in active/working memory. There is a reason that top sports atheletes practice all the movements they are going to do for their games, they want those skills to be automatic so they can focus on strategy.
Making skills automatic is critical to learning any subject. For example, try to name the following images without reading the text.
You probably had a very difficult time not reading the words on the screen. This is because, you have drilled reading so much, it’s become automatic for you. This allows you to not have to focus on recognizing what the induvidual words mean, but what words combined mean in a sentence, what thoughts are trying to be expressed to you in writing.
If you didn’t drill reading (by reading a lot) you’d have to spend a lot more time knowing what words “mean” instead of spending time digesting written information. Drills are important, and they make skills automatic.
Tip: Running drills is one of the most effective ways to get information into long-term storage
However, running drills can be boring. Since you already “know” how to do the drill, you don’t get that hit of dopamine if you’re forced to continuously do it. If you know how to write a stateful fuzz test suite, you might be adverse to doing it again. This is important for educators to know, since running drills will sap the mental energey of students.
You’ll need to balance these two:
- Running drills is one of the most effective ways to get information into long-term storage
- Running drills can be boring.
So this leads us to our next tip.
Tip: Be very specific on the drills you run. Focus on running drills on the skills you want to become automatic
This is where ChatGPT and Google come into play. There are going to be some skills that you’ll be able to readily look up at a moment’s notice, maybe don’t drill those skills. Skills that are important to drill for a security researcher might be:
- Recognize patterns in common vulnerabilities
- Write fuzz tests (Yes, drill this)
- Get context for a codebase by reading the documentation (reading comprehension)
“Over-learning” is when you re-learn something you already know, this is very helpful for making sure information stays in your long-term storage. Your brain cleans out long-term storage from time to time, and knowledge that is over-learned will get cleared out later.
You can think of your brain sort of like a “First In First Out” cache in this sense.
Do I need to have all the factual knowledge?
Today, we have tools like AI and Web Search to aide ourselves as developers, so long gone are the days where we need to drill every single concept because it would be difficult to find it later. Today, we can focus on drilling more advanced concepts, however we need to have basic facts memorized before trying to do more interesting things.
Imagine trying to have a conversation about whether or not to build a compiler as a static or dynamically typed languages without knowing anything about what those mean. This would be rather difficult.
Tip: Factual knowledge preceeds skill
It’s not possible to think deep on a subject without having the basic facts first. You don’t have to memorize everything, but you need to be very familiar.
How to become a better educator
As obvious as it may sound, this whole article could be summed up as some derivative of “know your students”. You should anticipate their needs. Know their background knowledge. Understand their wants. And after you do all this, you’ll need to practice doing it all again!
Tip: Deliberately practice your skill as an educator
Deliberate Practice
“Practice makes perfect” is an “Ok” phrase to repeat, but a more accurate one might be:
“Practice makes permanent”
Since whatever you repeat will become a habit. You’ll want to do deliberate practice, where you repeat doing something, and then reflect on that action to try to improve how you did it.
This goes for everything:
- Writing an article. How could I get more reads from this article?
- Writing documentation. Why did students leave feedback to say this post wasn’t helpful?
- Making a mock codebase. Why is no one forking my repo?
You’ll need to focus on your shortcomings and figure out how to improve them.
Understand experts learn differently than students
As educators, we might view a subject very differently than a student, and we need to keep this in mind. The image above shows the difference in eye movements in experts vs beginner readers. Based on the above, you’d expects schools to teach students to have much fewer eye moments, however, we find that it’s borderline impossible to teach a student to start there.
In the same sense, expert basketball players don’t need to spend time thinking about how to shoot the ball, that skill is automatic. They instead spend time thinking about strategies to get the ball closer to the hoop. However, we should still teach students how to shoot the ball correctly.
Tip: Understand that students may need to learn a different skill before attempting to do something the way an expert can
Avoid bogus
And then, additionally, be sure to avoid nonesense like the bit of information we started with at the top. There aren’t 3 or 4 types of learners, in reality, people learn much of the same way. Knowing where they are and what experiences they’ve had so far is much more important.
Conclusion
In conclusion, here are our tips that we use on Cyfrin Updraft that we’ve learned from years of doing this, and Daniel T. Willingham’s book.
- Keep the reward in the mind of the learner/reader
- “Memory is the residue of thought”, meaning the more we think on something, the more it’ll get stored in long term memory
- Most of writing is anticipating how your readers will react
- The best advice for teachers to improve is some derivative of “know your students”
- People are naturally curious, but not naturally good thinkers. Think of “to be learned materials” as answers, and spend lesson time on the question
- Factcual knowledge proceeds skill. It’s not possible think deep on a subject without factual knowledge first.
- It’s easier to learn faster the more you already know. This is because new knowledge is often anchored onto old knowledge. Knowledge can sometimes be viewed as “remembering a different way”. If you have a lot of old knowledge, you have more “surface area” to build off of.
- The best measure of whether a lesson is good is: of what and for how much will a student think
- Repetition is the mother of skill. Doing drills is the only want to solidify knowledge. Doing drills can be boring, since students will say “I already know this” but “over learning” is what drills it. You’ll have to find a balance of drilling students can losing their interest
- Think very carefully about what skills a student needs, and run drills on those. What skills need to become “automatic”. Don’t drill everything.
- Cognition is very different when a student is early in the subject vs late (an expert)
- Learners are more alike than different. Learning styles is not important
- Intelligence can be changed through hard work. Make sure students know they can improve.
- Talk about processes instead of ability. But don’t focus SOLELY on processes. The outcome is also important. For example “great work kid, you tried so hard” but only loses isn’t good. We’ll need to teach them to switch it up so they can get good results too
- Teaching is a skill and must be practiced, intentionally practiced.
- Improvement requires feedback and conscious effort to how well you are teaching
To learn smart contract security and development, visit Cyfrin Updraft
To request security support/security review for your smart contract project visit Cyfrin.io or CodeHawks.com.
To learn more about top reported attacks in smart contracts, be sure to study up on Solodit.
