Richard Feynman was once asked by a Caltech faculty member to explain why spin 1/2 particles obey Fermi-Dirac statistics. He gauged his audience perfectly and said, “I’ll prepare a freshman lecture on it.” But a few days later he returned and said, “You know, I couldn’t do it. I couldn’t reduce it to the freshman level. That means we really don’t understand it. [1]

Explaining things is hard. It requires knowing that thing intimately, back to front. Putting yourself in the mind of someone who doesn’t understand reveals what you don’t understand. It’s an exercise in empathy, and a skill that can be honed.

Effectively explaining is very satisfying, and is a useful skill to develop. As software engineers, a large part of our responsibility is not only understanding things, but to explain them too. Many times a day, we need to explain things to new team members, product managers, designers, and even people from completely different disciplines.

Is React easy or hard to understand?

I’m going to be honest: I’ve had a hell of a time getting my head around React. More than any other technology I’ve touched over the last 10 years of my career, I just haven’t had it click for me. It’s very frustrating as I really want to learn it, and it’s clear the library has legs.

– Brad Frost, http://bradfrost.com/blog/post/my-struggle-to-learn-react/

This isn’t the first time I’ve heard someone say that React is hard to learn. However, I’ve also heard people say “The core concepts of React are easy to understand!”.

So, which is it? Is it actually hard to understand React? Is it more or less hard than understanding another framework?

There’s no definitive answer. React will be easy to understand for some people, and harder to understand for a different set of people. People come with a different backgrounds, and a different set of “mental models” (more Richard Feynman stories, sorry 😅), which means that the core concepts of React will be easier or harder for different people!

For someone who has worked a lot with web components, React has a nice home in that person’s set of mental models. However, for someone who has only really used jQuery in an ad-hoc way, there are lots of new concepts to understand, and care must be taken when explaining to cover those.

If lot of concepts of React are new to people, it’s useful to know how people understand things, so that we can more effectively explain.

How to explain React things

It took me some time to realise the way you understood React isn’t the way that someone else will understand it.

There are many reasons for this — people come from different backgrounds, with different experiences. They may be more used to how Angular works, or Backbone, or maybe they’re used to using jQuery to manipulate the DOM directly. They might have limited javascript experience, or they may know everything there is to know about ES6. The important thing is to spend time getting to know the background of the people, or person, that you are explaining things to. People learn new concepts by relating them to things they already know, and this can be encouraged with good analogies and comparisons.

Another key reason why someone else won’t necessarily understand it in the same way is due to history, and time. I was talking with a friend recently about how rapidly things change. “Front end stuff just moves so fast! I learnt javascript a year ago, and the next time I came back everything’s different!”. Gradually building up concepts over time made learning React straightforward for me, but for somebody who is confronted with React, ES6, Webpack and JSX all at the same time — these are all new concepts that are easily confused with each other.

So, how can we explain better?

If you don’t pay careful attention to these differences in experiences, your explanation won’t be effective. Depending on whether you’re explaining 1 on 1 or in a group setting, there are different strategies for approaching these varying experiences.

Ask questions regularly. This gives you an opportunity to check in on the person you’re explaining things to. It engages the other person, and makes explaining an interactive process, rather than a passive one. Ask questions that encourage engagement. Instead of asking yes or no questions like “Does this make sense?” (often met with empty nods or “uh, yeah.”), ask “what” or “why” questions, like “What would happen in this situation?” and “Why is this piece of code important?”
Be prepared to change tacts. Since there is a wide spectrum of experience, in a 1 on 1 setting, you should be prepared to tailor your explanation to the individual. This is better as it helps them relate to the knowledge, and allows them to engage more.

Give the right level of detail. If you know something in depth, it’s tempting to deep dive into interesting but unimportant details. Be prepared to use abstractions or skip parts that aren’t relevant to ensure your explanation meets the experience of your audience (note: this doesn’t mean you should simplify to the point of being incorrect )

Examples

Specifically with React, there are common confusing points for people who haven’t been following closely.

ES6 vs. JSX

Introducing these two concepts at the same time is often confusing for people. Looking at the following code sample, we can see there are multiple new concepts combined

import * as React from 'react'; //ES2015 + React
import * as ReactDOM from 'react-dom';  //ES2015 + React
const allCaps = s => s.toUpperCase(); //ES2015
class HelloWorld extends React.Component {  //ES2015 + React
  render() {  //ES2015 + React
    const { name } = this.props; //ES2015
    return (
      <p>Hello, {allCaps(name)}</p>{/* JSX */}
    );
  }
}
ReactDOM.render(<HelloWorld name="Josh"/>, document.getElementById('app'));

Starting off with an overview of which parts are ES6 can be helpful if the person is unfamiliar with this new syntax.

I also made a tool, “React or ES2015”, to help with this. Pasting a code snippet, you can see which parts are React, JSX, ES2015, or ES5, and click through to relevant documentation for each part. This tool may not be helpful to someone who can immediately tell which syntax come from where, but there are many people for who I hope this is useful!

Why are there so many ways of creating components?

A React component can be defined as a class, a function, or by calling React.createClass. This is a confusing point for people new to React. Introduce this concept carefully — provide clear guidelines on when to use each of them, to avoid unnecessary confusion (will you use state? Use a class : Use a function).

The overall model

This is my favourite part to explain, as I think it’s one of the greatest parts of building UI in React. The overall data flow model is generally easy to understand, and understanding this basic concept is a useful mental model.

This is also a great opportunity to compare with other languages, approaches and frameworks that the user is used to. Comparing and contrasting the approaches will help solidify the concepts in the learner’s mind.

From https://facebook.github.io/flux/docs/in-depth-overview.html#content
Pointing out that React is the view layer in the above diagram helps clear up ambiguity around React’s job.

The fundamental idea of the flux model is useful to know, but give the right level of detail, and don’t spend too much time in the abstract. Seeing how things follow this model in practice is more useful than an in-depth, abstract explanation of the flux model.

Helper libraries

When creating demos or writing examples for people, be careful to not depend on helper libraries that are not relevant to the point you are trying to convey. If you’re trying to make a point about React state management, avoid using lodash, react-router, react-intl, or anything that’s not directly related to what you’re trying to explain.

While it’s clear to people familiar with lodash that _.concat isn’t the point of your example, this can be a confusing distraction for people unfamiliar with lodash, and the point you’re trying to make.

State

Another common question relates to what type of state to use. This is getting more confusing for beginners as there are many new alternatives — each with some advantage (they’re small, they’re not running in the main thread, they’re wired to GraphQL, or they’re just using normal React features like store and context).

Personally, I find these new developments exciting, but understandably, new learners find the amount of choice here distressing. Providing clear guidance helps mitigate this. Pick one of these and learn that to begin with — when you’ve come to grasp the main concepts of React, the nuance of which store is best becomes a more relevant question.

How to explain in general

Research shows that people learn more effectively with active, rather than passive learning [2]. Active learning is a style that encourages learners to analyse what they know and do not know. For an explainer, this means encouraging questions, and also asking questions regularly to keep the learner engaged. People also learn more effectively when they are given control over what they want to learn, as this encourages engagement [3].

Once someone is engaged, learning can take place by relating new concepts to existing ones that they already understand. Learning and remembering new ideas becomes easier once that idea finds a place in our set of mental models.

Why all of this?

Front end development is great, and getting better all the time. The way that we can continue making the technology, and the community even better, is by putting effort into explaining things clearly and effectively. More people can learn, become experts, and share new, diverse ideas.

Communicating how technologies, and React, work, is a key part of this. The way you understood React isn’t the way that someone else will understand it, and with some conscious effort, we can get better at sharing our ideas about things with each other 😁

👋 Hi! I’m Joshua Nelson. I’m a developer who cares about making the web a better, for everyone ✨

This is a cross post from https://medium.com/@joshuanelson/react-explaining-explained-13a3fe6e5b9d

1. Six Easy Pieces: Essentials of Physics Explained by Its Most Brilliant Teacher
2. (Bransford, 2000, pg.15–20)
3. J. Scott Armstrong (2012). “Natural Learning in Higher Education”. https://faculty.wharton.upenn.edu/wp-content/uploads/2014/09/Natural-Learning-in-Higher-Education_2.pdf