One day, I was thinking about the process of creating educational material around React. It’s something I’ve been considering getting into and I became genuinely curious to see how fast I could get a project up and running with the tool Create React App. It turns out, the process was pretty straightforward. In just a couple of minutes (and using only 1 command), my project was generated, all the NPM packages were installed, and the repository was initialized in Git.

Once I ran npm start and had the project running in the browser, I realized something about my experience: I was able to get an entire app up and running without having to constantly check the docs.

How come I didn’t have to keep referencing the documentation in order to know what to do next?

After I thought about it, I realized the instructions were following me around!

Background

When I started getting into building educational material with React, I wanted to find resources online that could help developers of all levels get more familiar with React code samples and apps. When you can reduce the time it takes to get a project set up, you can spend more time diving right into the parts of the code that matter for what you’re looking to learn at that point in time. In this case, it was about building React components. So I figured finding the tools online that could take care of the set up “under the hood” would be helpful and easier for folks to follow along.

What’s great about tools like Create React App is that the commands I need to run create the project, install all the necessary node modules, a package management system, include tools to write tests with, format code, a JavaScript compiler, and a README template that would make the app easy for another person to run.

The process involved running npx create-react-app [name-of-your-app] and no further configuration was necessary! I sat back and watched the scaffolding of the project in my Terminal. For creating a single-page React app, that’s a simple and painless single step process.

My Epiphany

What was interesting about getting my React app up and running was that I didn’t have to constantly check the docs online to figure out next steps.

Why was that?

From the first step of running the project generation command, the Terminal output provided logs of what was happening under the hood.

Installing packages. This might take a couple of minutes.
Installing template dependencies using npm...

After that, it let me know that the project was successfully created and provided several commands that I could immediately run once I navigated into the app’s directory.

Success! Created hello-world at /Users/nnenna/Projects/hello-world
Inside that directory, you can run several commands:	npm start
		Starts the development server.	npm run build
		Bundles the app into static files for production.	npm test
		Starts the test runner.	npm run eject
		Removes this tool and copies build dependencies, configuration files
		and scripts into the app directory. If you do this, you can’t go back!We suggest that you begin by typing:	cd hello-world
	npm startHappy hacking!

With the next step suggestions listed as part of the Terminal output, these were the instructions I could trust to run my app and view it in the browser. Since I was interested in seeing the app run smoothly after the project had been created, the natural next steps for me were the suggested commands. cd hello-world and then npm start!

When I ran the script, the development server kicked off, the code compiled, and my computer automatically pulled up my browser at the URL localhost:3000. I was met with this view in my browser:

So, the app was running! And interestingly, further instructions to start coding were part of the view in the browser! It tells me:

• exactly where to start editing the code in my project

• that I have hot reloading capabilities so I can see immediate changes that I make in the code show up in my browser without having to kill the server and restart the app to see the most updated version of the code

Although the steps to get setup weren’t tedious or complicated, there were instructions guiding me from the beginning of the process (in the docs), in the Terminal output that gave me commands to run, and finally, in the browser where I landed to see the app running. It was like I had a trail of instructions that greeted me at each checkpoint in the process.

At the end of my setup journey, I was given the baton to take it away from there and build what ever kind of single-page React app I wanted. Because the instructions were “following me around”, I could trust that the information right in front of me at each step would be the most important stuff I’d need to accomplish my goal: to get the project set up and running.

This experience made me a bit curious about what others thought about instructions existing beyond docs. So, I took to Twitter to ask the community. Interestingly enough, here was a response I got:

Bingo. The word that comes to mind to describe why we can get value out of this style of documentation workflow is empathy. We all have different learning styles and the community benefits from empathetic documentation writing!

Conclusion

Typically, I’m accustomed to relying on the docs online to provide me with next steps. While the Create React App docs do provide all the steps necessary, it became more of a post-setup confirmation that I had everything I needed to begin coding.

When reading docs and interacting with the CLI, it’s sometimes easy to get a little lost with the different parts of your machine that you have to manage in order to ensure you’re doing the right thing at the right time. The browser, the Terminal, the code itself in your editor, etc. The more complicated, lengthy and descriptive the set up process is.

But regardless of the level of complexity of documentation, I couldn’t help but think about how helpful it is that instructions are visible in each place that the developer has to navigate to on their machine.

Find me on LinkedIn for more content :)