Gatsby Starter Blog RSS Feed

How to Be a Great PR Reviewer

Fri, 02 Feb 2024 00:00:00 GMT

The other day, one of my teammates asked me for advice about how to get better at doing PR reviews. Here are some of the ideas I came up with:

Read Code and Learn What Good Code Looks Like

To start with, it's important to understand the purpose of code:

To define a process so people can understand it.

That's right, code is not for computers, it's for people. The computers will
run assembly code that's very difficult for humans to read; we've developed programming languages on top of that hard-to-read code to make it easier for us to understand and discuss with others.

The code has to work, yes, but it's main goal after that is to be readable!

Here are a few things I expect from readable code:

It's not too complex or surprising. It follows existing patterns.
It's not too short or too long. It's concise.
There's a decent chance a non-programmer could figure out what it's doing. It's written in "human" as much as possible, not full of programmer jargon.

Reading good code can help you understand what that looks like and how to suggest changes that will improve other people's code.

But where do you find good code?

Thankfully, other people have had the same question and answered it for us. Here are a couple codebases that have some pretty good code:

And one person that created their own list: Max Rozen

To start with - I recommend checking out JSX files (.jsx or .tsx) in a components directory if you can find it - it's often something like src/app/components/.

And here's a repo with suggestions about how to write good code: clean-code-javascript

So read code. A lot. Stop and figure out what something confusing is about. Go to some code that you don't know is good - see if you can tell whether it is or not. And of course, see if you can make your next PR a little more readable, too!

As one final note, don't forget that there's a difference between good code and style. There are many different ways to format and organize code - 2 spaces vs. 4 spaces vs. tabs for indentation, etc. Use the style guide for your organization or try to get your team to agree on one from somewhere else and use that. But style is just how the code is formatted. Good code can be created in any style.

Find Good Mentors and Teachers

There are a lot of software developers of all levels writing blog posts, making videos, and recording podcasts about software. They'll all tell you what they think is the best way and what they think you should know, but how to tell who really knows?

One good way to tell: Do they talk about tradeoffs?

Software engineering has a lot of tradeoffs:

How good can we make the next feature vs. how fast can we get it to the users
Using the first variable name that comes to mind vs. taking the time to brainstorm
Picking a library you know vs. taking more time to research possible alternatives you'd have to learn how to use, but might work better
Discussing coding styles with your team so there's a consisent, readable style vs. using that time to get more code written, even if it's harder to read

Different teams, projects, and technologies may cause one side of the tradeoff to become more important so many of these don't have one right answer - it's all about finding a good balance for your project and organization.

Let's look at some quick examples. Here's a more basic, surface-level suggestion:

Make sure your code is DRY. If you're writing similar code in multiple places, create a function to do it in one place and call the function. This makes it so -you only have to edit one place if you need to change that code.

That's a great suggestion! It's definitely a skill you should develop and know when to implement.

But check out a more advanced suggestion:

Definitely think about making your code DRY, but don't rush into it. Before you create a function to replace code in multiple places, ask yourself: "Will these areas change for the same reason?" If I need to edit it in one place, will the others definitely need to change, too. If you're not sure, wait.

If the code isn't perfectly DRY, that's okay. Better a little "wet" code than too much coupling that makes the code difficult to change later.

Side note: For more info about the tradeoff's with DRY code, check out a different acronym: AHA (Avoid Hasty Abstractions)

Improve Your Communication Skills

This is good advice for just about everyone everywhere. But in the context of PR reviews, I'm thinking about 2 specific goals:

Be consistently respectful (even if you have to be firm)
Be able to clearly share your point of view (even if you don't end up convincing them of your idea)

Be Respectful (in every comment)

Here are some of my rules to keep my comments and communication respectful:

Write things out: Don't leave off words to save time - it sounds terse, short, and potentially rude.
Always talk about how "we" can do things to make "our" code better: If you're doing reviews, you're on some kind of team so keep that in your words, too. Besides, after a few suggestions from PR reviewers, it's no longer just code written by the PR author - it's code written by all of you!
Write like you know you could be wrong: Use questions and phrases like "it seems like" and "I think" before comments like "this is no longer needed". (It's a lot easier when you do make a mistake, but it's also easier for the reader to take the feedback and really consider it.)
Try to encourage discussion: Instead of just making a suggestion, consider opening up with a couple ideas and ask for additional ideas from the PR author. Even if you already have an idea, you never know what you might come up with together!

Examples:

Can we remove this function? It looks like it's no longer needed.

Note the "we" and the question. Also "it looks like" - assuming you could be wrong.

How about we change this name from BookList to BookCollection?

It's a question and it's using "we".

What do you think about trying to refactor this using a more general component?

Attempting to start a discussion about possibilities instead of making a specific suggestion - a great way to leverage your team.

Be Clear

Learning how to clearly communicate your thoughts takes time, but you can help speed up the process with some deliberate steps:

Take notes of good exchanges where it's clear your comments were understood right away by the reader. How did you make your ideas clear?
Take notes of lengthy exchanges where you had to re-state your ideas multiple times - how did you say things when they were finally understood? How was that different from the first comment you made?
Revise your comments to try and make them shorter without losing meaning or leaving out anything. Can you say the same thing with 75% of the words? Half? 20%?
Ask for feedback every once in a while! E.g. "I noticed it took a while for us to reach an agreement in that discussion. Could I have done anything to make that easier?"

Learn to Think About Risks, Value, and The Big Picture

Risks

This is both a simple concept and a difficult one to measure well. Risks are what could go wrong. If a variable name isn't perfect, the code will still work, but it may be harder for other developers to read and understand. However if a date isn't converted properly, that could lead to a significant bug. One clearly matters more than the other because the risk is bigger.

Spend more time reading, thinking about, commenting on, and discussing riskier parts of the PR.

Don't be afraid to leave off comments about refactoring, names, or small changes to avoid distracting too much from risky areas that definitely need a change or a small discussion to make sure things are handled the right way.

Value

Finding bugs is the best. Suggesting refactorings that can make the code easier to read or edit is super helpful. However the 20th name change is not as important. And making too many suggestions about old code that wasn't changed quickly becomes annoying.

Try to consider how much your suggestion will impact the users of your software, the amount of money your company makes (if applicable), and how much your team will appreciate the change. Then decide whether it's worth the time it'll take to make it.

And if your Project Manager would love how it helped them meet the estimate they shared with upper management - by avoiding a bug that would have delayed work or ensuring something matched the specification so it would pass final testing - that's always a high value!

The Big Picture

Always take a moment to "step back" and think about the bigger ideas. Does the code do what it's supposed to? Does the overall structure of the files and code make sense? How long are you spending on the review?

Make sure you don't get stuck suggesting name changes and how to remove nested ternaries and then forget to check the overall functionality or structure. Not every possible improvement needs to be made on this PR.

Also, consider the number of commments - if you've got 50 comments on a small to medium size PR, that's probably too many. Keep the most important ones and see if you can delete a few without significant risks or loss of value.

Conclusion

It takes many different skills to review PR's well. I think that working on recognizing readable code, finding good teachers, improving your communication, and remembering the big picture are good areas to focus on to increase your effectiveness with PR reviews.

I hope that's helpful and good luck with your reviews!

React in Detail: Elements, Components, and HOCs

Fri, 11 Oct 2019 00:00:00 GMT

At Metal Toad, I’m part of a team of developers who often work on code together. Whether it’s pairing with one other person or mobbing as a larger group, teamwork is an important way we help each other and provide the best value to our customers.

And teamwork requires communication. The better the communication, the more effectively ideas can be shared and topics discussed. And while there are lots of resources out there for general advice about how to communicate well, and we have dictionaries and thesauruses when we need to figure out what words mean, industry-specific language can be more challenging.

Whether you call it jargon, lingo, or something else, some words only make sense in the context of a specific industry. In the case of software development, sometimes a specific programming language, library, or tool even has its own terms. And you won’t find them in most dictionaries.

Because they’re so specific to particular fields and are often taught verbally to new people as they’re learning the ropes, it’s much easier for there to be misunderstandings around some of these words. Today, I’d like to talk about a few of those words in the context of React.

What is React?

If you aren’t already familiar with it, React’s purpose is to speed up the display of the user interface for web apps. It’s a JavaScript library that acts as an intermediary between business logic and the browser. As a developer, I tell React what I want to appear on the screen and it works its magic to make sure those things appear quickly and update efficiently as the user interacts with them.

A responsive and snappy user interface is an important part of any application so it’s easy to see why we use React at Metal Toad - because we care about the experience of our users and are dedicated to using the latest tools to give them the best experience possible.

Now that you have some context for why we use React, let's look at the smallest parts of a React app:

Elements

React elements are the building blocks of React. They are objects used to create a representation of each part of what should be displayed on the screen - each element, you might say.

So what does an element look like in code? It looks like this:

<div />

Or, if you're working on a project that doesn't use JSX, then it would look like this:

React.createElement('div')

(JSX compiles to regular JavaScript functions - see how it works with Babel’s interactive compiler.)

That function call creates a JavaScript object which includes all of the information React needs to display that piece of the user interface and control it. You might recognize this element as the humble <div> tag from HTML. In fact, that is the code to create that tag in React. Of course, the fun really starts when we combine multiple elements. Let's look at a larger element:

<div>
  <h1>React Stuff You Need to Know</h1>
  <p>Here is some stuff about React…</p>
</div>

As you can see, there are 3 elements here: <div>, <h1>, and <p>. However, this code still only returns one element. Why? Looking at the non-JSX version will be helpful here:

React.createElement('div', null,
  React.createElement('h1', null, 'React Stuff You Need to Know'),
  React.createElement('p', null, 'Here is some stuff about React…')
)

The three elements are definitely created, but the two child elements become a part of the parent element. The parent element function call takes the function calls for the children as two of its parameters so the end result is one return from the parent function call.

So far we've been just using standard HTML tags as React elements. Let's switch now and look at how you can create your own elements:

Components

In React, a component is a function that returns a React element. Let's take a look at one:

const ReallyCoolComponent = () => (<div />)

Here are a few other ways of creating the same function using different JavaScript syntax:

function ReallyCoolComponent() {
  return <div />
}

const ReallyCoolComponent = () => React.createElement('div')

function ReallyCoolComponent() {
  return React.createElement('div')
}

Now this is a pretty basic component - and frankly, not super useful - but it illustrates all of the requirements for a React component: It's a function It returns a React element

That's it! If it has those two properties, it's a React component.

If you've used React some, you might have some objections to this simplistic definition:

Q: What about Class components?

A: Yes, you can use the class syntax to define a React component and it is different than simply defining it using a function, but ultimately it is still a function. Don't believe me? Try it yourself in a Repl.

Of course, this doesn’t mean that a functional component and a class component are the same. It just means they both fit the description of being a function.

Q: Doesn't React accept other things besides React elements in the return of a component?

A: Yep, you've got me there. Strings, numbers, booleans, and null are also allowed. The first two are turned into React elements automagically and the other two are ignored (but valid). For simplicity, I'm including all of these things under the umbrella of React elements because React treats them all like elements (or the lack thereof).

Q: What about props?

A: Good question! Although props are almost always used in a component, they're not actually required. If they are used, though, they add two additional rules:

The only parameter a React Component accepts is one object called 'props'.
The component must act like a pure function with regard to it's props.

Let's look at a component that accepts props:

const ApplePicker = (props) => {
  return (
    <div>
      <p>{`I picked ${props.picked} apples today!`}</p>
      <p>{`I should pick ${props.totalNeeded - props.picked} more…`}</p>
    </div>
  )
}

You can see that it accepts a single parameter object. In this case, it expects that object to have two properties called picked and totalNeeded. It can then use those properties to display data and, in this case, calculate how many more apples should be picked.

Importantly, the component doesn't change its props or take in additional parameters. That's what it means to act like a pure function with regard to it's props (our last rule).

Here’s the complete list of rules for a React component:

It must be a function. (Classes are functions.)
It must return a valid React element (including string, number, boolean, or null).
If it accepts parameters, it should accept one parameter object called props.
It must act like a pure function with regard to its props.

Now that we have a pretty good handle on elements and components, let's take a look at the next step up from there:

Higher-Order Components

What’s a higher-order component? Just like a component is a function that returns a React element, a higher-order component (HOC) is a function that returns a React component. Let's jump straight in with an example:

const withData = (data, AComponent) => {
  return (props) => (<AComponent {...props} data={data} />)
}

And for clarity, here it is without the JSX:

function withData(data, AComponent) {
  return function(props) {
    return React.createElement(AComponent, {...props, data})
  }
}

This is definitely a function, but is it an HOC? Let's do a quick check to see if what it returns is a React component using our four rules for React components: Is it a function? Yep! Does it return a React element? Yep. (Note: AComponent is a React component, but <AComponent … /> is a React element.) If it accepts parameters, is it one parameter called props? Yep. Does it act like a pure function with regard to its props? It does indeed.

Success! Since this function returns a component, it’s a higher order component. As you can see, it appears to be adding data to the props of AComponent. This is one of the common ways HOC’s are used.

Don’t Forget Context

If you’re like me, you might already have realized that you’ve used one of these words incorrectly in a discussion about React. Especially when it comes to elements and components, the words are also used in more general ways so it’s easy to confuse them. That’s why it’s important to clarify the context for how you’re using these words. Usually, simply adding ‘React’ in front of ‘element’ or ‘component’ can help everyone follow you.

I also found that, when I tried to explain higher order components to a coworker, I couldn’t clearly articulate what I knew. That made it so even though we took the time to try to close a communication gap, we couldn’t quite do it on the spot. (It also led me to do the research that ultimately led to this blog post.)

Hopefully, this article has helped you to solidify your understanding of these concepts so you can use them confidently and help clear up any miscommunications that may happen to you and your team. Thanks for reading!

Other Resources

To continue reading about this subject, I recommend checking out these other great articles:

The React introduction pages for Elements and Components (in that order)
Dan Abramov's article about React Components, Elements, and Instances

My Programming Journey

Fri, 13 Sep 2019 00:00:00 GMT

My First Programming Language

At some point after I learned to read, but before middle school, I took an interest in computers and used my dad's IBM PC - this one - to learn BASIC, a programming language designed to be simple. It had a good name, right?

I started trying things out on my own but soon teamed up with my best friend from across the street. We made simple computer programs in BASIC and then C++ and eventually in Java - the newest language at the time.

Through that early experimentation, I learned the ins and outs of logical procedures, debugging code with cryptic errors, and how to communicate ideas about how a program should function and how it could look.

My First "Job"

In middle school, I had an awesome Geography teacher named Mr. Rogers. He was technologically advanced for a teacher at this time because he regularly used a digital projector and screen to display lesson information at a time when chalkboards were still common and overhead projectors were the only similar technology in everyday use in the classroom.

He also regularly gave tests via computer. On test days, we would all go over to the computer lab and use the PC's with Windows 3.0 to demonstrate our knowledge about countries in various time periods - their names, locations, and major events associated with them.

So it's not surprising to me that Mr. Rogers also allowed students to turn in some assignments in the form of web pages. Looking back at this, I realize what a brilliant educational incentive that was, but at the time I simply thought that it was a cool way to type up my report and not have to print it out or hand it in. No “the dog ate my homework” issues for me!

It's because of that report - and the fact that I coded it by hand in HTML rather than use software to create it - that Mr. Rogers invited me to redesign the school's web page.

This was around the time that Animated GIFs were still the new hotness so it seemed like every web page had at least one waving flag, animated smiley face, or dancing cartoon character. I simply had to choose a reasonable color scheme and avoid the temptation to insert unnecessary motion graphics and my school's web page went from looking like a MySpace page to looking professional.

Speaking of web pages: It was only a few years after that when Google came out. I can still remember doing my first Google search in 1998. Things have come a long way since then, haven’t they?

A Proliferation of Technology

Today, the number of programming languages used to create software has increased to over 100. The language I use most right now is JavaScript and within that one language, there are over a million libraries and modules to choose from to help build software. Stack Overflow, a site where software developers can answer each other's programming questions, has grown from its humble beginnings in 2008 to a staggering 10 million plus users in 2019.

To say the least, there are a dizzying array of options out there when it comes to technology. npm

Making a Choice

I got involved in software development specifically because of this kind of problem. A lot of people find the plethora of technological choices to be overwhelming. In addition, even once you've made a choice, it can be difficult to figure out how to best use the technology to achieve your goals. This is true whether you’re envisioning a network of systems reaching around the globe or simply installing a new version of Excel!

My passion is closing that gap: Creating software that's designed specifically for people to help them achieve their goals.

And that's also why I now work for Metal Toad. As a company offering custom solutions at the leading edge of technology, Metal Toad exists to help customers find technology solutions that allow them to meet their goals. Whether its discussing the best options for a new project in a discovery phase, leading the charge on getting a new system up and running so it starts out in the best possible way, or planning and executing a successful technology upgrade, Metal Toad takes care of solving technology problems so they can focus on how to solve the problems of their customers.

With the every-increasing amount of technology out there, it just makes sense to work with a company that makes being familiar with technology it's business. I'm glad that I get to be a part of that.

How I Deployed My Web Site

Thu, 27 Sep 2018 00:00:00 GMT

As promised, here is Part 2 of re-designing my web site. Check out Part 1 if you missed it.

Netlify

I like to meet up with other developers outside my work from time to time to learn as much as I can about software, the industry, and new technologies. It's also fun swapping stories.

During one such conversation, I mentioned that I was looking for an easy way to host my website. It had to be free and ideally it supported some kind of continuous deployment.

His suggestion: Netlify. Here are some of the features they offer:

FREE (for small sites) - This one is big for me right now. I don't need much and don't want to pay much.
Continuous deployment with GitHub integration
DNS Servers and Domain Management - My current domain name company doesn't have a great website. I love being able to just point my domain to Netlify's servers and manage everything via Netlify.

Pushing From GitHub

Even though I didn't think of this as a requirement for my new hosting solution, I can't imagine ever going back! 15 seconds from commit to updates live on my web site - this is a game changer for me. This is sooooo fast compared to how I used to update my website.

I used to hate updating my website by uploading new files. I also would have to test things out before uploading and check quickly after the new files went live to make sure everything was working correctly. Combine that with the slow process of editing, saving, and checking the results in a browser and I was always putting off updating my website due to the hassle.

Now I can make quick changes to text or even simple code changes right on GitHub. Not only do the changes go live seconds after each commit, but there's also error checking baked into the build process. If anything goes wrong with the build, no changes make it to the site. This is nice insurance against mistakes making it online.

One other benefit: Any changes I make to my site are included in my GitHub history. I don't know how much stake hiring managers put in those green squares on my GitHub page, but I like the idea that I'm getting credit for all of the coding I'm doing.

Web Page Testing

An important part of any website project is web page testing. Does your site load quickly, are you caching resources correctly, and is it accessible? Most of this is handled automatically by Gatsby so I don't have to worry about it, but it's important to check.

For all your website testing needs, go to Web Page Test.

Progressive JPEG Compression

One thing that's not automatically handled by Gatsby is Progressive JPEG Compression. It's worth using technological advancements that solve problems and one recent solution in images is progressive compression. You've probably seen pictures online that load as blurry or very simple images, but get sharper or more complex after a few seconds. The idea is that this enables you to see the layout of the page and an approximation of the final image very quickly. Often that's all that's needed to give you context for what you're reading so I highly recommend taking advantage of it.

Here's a great article about progressive JPEG's - it has green martians! (And useful information, too.)

The solution I chose to make progressive JPEG's was to install mozjpeg using Homebrew (on MacOS). I wasted a lot of time learning about compiling from source code before I realized a Homebrew install was possible. I wish I had seen that earlier, but such is life. :-)

I'm currently running it from the command line by hand, but I plan to explore adding mozjpeg into my Gatsby configuration so I can automate the process.

I Had Fun

Even as I write this blog post, I'm simply editing a file on GitHub. Sometimes I use my development environment, but other times I just edit right in my repo - it doesn't publish until I push to the master branch so it's safe to draft, revise, and tweak on GitHub! Even after I commit on the master branch, nothing goes live unless everything compiles correctly so I know I'm safe from simple mistakes causing my site to go down.

In then end, I really like Netlify as a host, but the important thing is that I'm leveraging modern technology to make my life easier. Continuous deployment is an awesome tool that speeds up my web development and I highly recommend it!

The Weird Reason My React App Failed on Chrome for iOS

Wed, 26 Sep 2018 00:00:00 GMT

If you haven't checked out my portfolio, you may not know that I pioneered a move to React for a web app I support at work. This app displays event orders so technicians can deliver the correct gear to events in the building.

The App's Not Working!

It's never fun to find out that the app you've been slaving away at for days and you thought had just been successfully released doesn't work on a user's device. It's hard to test every single device so I doubt this is uncommon, but at work we have a direct connection to our users and can specify which browser they use to access our app so it was surprising to have this happen.

Anyway, the issue was that the main page that displays events wasn't displaying anything at all. It seemed to only be affecting users connecting on iOS devices so that's what we had to go on.

Troubleshooting Begins

One of my strengths in software development is isolating a problem to help solve it quickly. My process involved some straightforward questions and digging to verify the answers:

Is the HTML page loading ok? (Looks like it.)
Is the React container showing up? (Yep.)
Is the React app rendering? (No...)
1. Because of React itself? (No. It's loading fine.)
2. Or React-DOM? (No, it's also working. Simple substitution testing shows that React renders a simple element fine.)
So everything's working, but the elements aren't showing up? (Yep...)

From there, I dove into the code that controls which elements show up and where. The primary issue became apparent - events weren't showing up because their dates weren't getting figured out correctly. They were correctly filtered, but the dates themselves were bad somehow.

Documentation

As I've grown as a devloper, I've come to love good documentation. MDN is an awesome reference for all things JavaScript, HTML, and CSS so that's where I turn for solutions (after a quick Google search to scan Stack Overflow - no need to solve a problem someone else has already solved).

Here's a sample of the type of code I was trying to verify: const eventDate = new Date("2018-09-26").

Sure enough, the docs confirmed that the ISO 8601 date format is an accepted parameter for creating a new date.

Just for kicks, I tried const eventDate = new Date(2018, 8, 26), using an older style initialization.

Voila! It Works! But Why?

Changing the date initialization format caused everything to work correctly again. That was great, but I wasn't satisfied.

I love it when things work, but I also hate not knowing why they worked. What if something changes and the "same" solution fails next time because I didn't truly understand the underlying mechanism? Sometimes time is of the essence and moving forward is too important to linger, but most of the time I don't think I'm doing my job right unless I know why a bug fix works and how to prevent the same issue again next time.

To get to the bottom of the issue, I consulted some of my favorite tools for checking on specific compatibility issues: MDN's chart at the bottom of each page, Can I use, and if those don't work - Stack Overflow again.

It took me a while, but I eventually found this gem: Chrome iOS - Is it just a UIWebView?. It turns out that Apple requires all apps on the App Store to use their renderer for showing web contect (the same as Mobile Safari uses). Essentially, supporting Chrome actually means supporting Safari on iOS, too. Any client-side rendering of JavaScript is handled by the same engine - no matter what browser you use.

Takeaways

What did I learn through this process?

I'm actually OK at solving tricky compatibility issues. Sometimes I've felt like I haven't had a really tricky bug in a while and it's nice to get something like this and see that I can come out the other side on top.
Even narrowing supported browsers and OS's can leave you with surprises you didn't foresee.
Getting to the bottom of an issue is both rewarding and worth it!

How I Overhauled My Website in a Day

Tue, 25 Sep 2018 00:00:00 GMT

I had been putting off redesigning my website for way too long. Everytime I thought, "Dude, you need to update your site...like yesterday," I also remembered all of the steps that would take:

Choose something to update like adding a new project.
Go make sure the project looks good on GitHub and wherever it's hosted.
Write up a short explanation for it.
Screenshot it or pick a nice image to represent it.
And NOW I can actually start the website update...by trying to remember my AWS password (my last host).
After I give up on guessing my password, I go through the annoying process of resetting it.
Now that I'm logged into my host, I'm ready to update my page - HTML & content - and upload the photo.
If all goes well, that's it.

Phew! I know I'm being a little dramatic and some of those steps could be simplified if I took the time to work on them, but it really was a burden that I didn't want to mess with.

And that's why my site languished in its outdated state for a so long. Until one day I had...

An Important Conversation

As part of my growth as a developer, I try to meet up with other developers - especially people who are more experienced than I am.

One such conversation was with a Senior Developer over coffee. In addition to getting his take on the market, finding out about what he did and what technologies he used, I also asked him about his suggestions for some typical development tasks.

Since I had heard a lot about Gatsby recently, I asked what he thought about it for a simple site and he encouraged me to try it out. The most importat thing, he said, was to spend no more than half a day. If I couldn't get it working by then, he recommended I try something else.

That seemed wise. Even if it doesn't work out, what's half a day if there's a chance I'd have an updated, more stylish site at the end?

My First Static Site Generator

I know Gatsby is more than a static site generator, but for my site that's really all I needed from it. And its website was very encouraging:

Install Gatsby.
Start a new project from a template.
Run gatsby develop to host a live-reloading version of your site locally as you edit.
Run gatsby build to create the polished, web-ready version of your site.

That is somewhat simplified, because I did have to choose a template, but that's the only other thing I needed to get off and running.

The Joy of Editing and React

As I got into the groove of editing, it was awesome to see my site update on every file save. I've had this type of experience on CodePen and various other places, but Gatsby's version just works well.

I also enjoyed how React was integrated into the project. Making changes to the actual layout or functionality of the site was easy because I'm very familiar with React - I use it at work right now and love it!

Time flies as I enjoy the process of taking the template I started with and making it my own. Before I knew it, I was looking at a modern, professional version of my site - I was ready to show it to the world!

The Hiccups Begin

And here is where I hit my first problem.

When I went to build my site, the command failed! I had spent hours writing, sourcing images and taking screenshots, and tweaking the look of this site and now it was all going to be for nought!

I hated how perfectly Gatsby had got me off and running only to dash my hopes near the end!

But being a good developer, I started to troubleshoot. That is, I Googled the error code. It wasn't popular and most of the hits were from GitHub issues. I don't want to find out other people are having the same problem and they think it's the software itself...

After some researching and back-tracking, I figured the problem must be that my starter template was for Gatsby v1 and I had installed the latest version - Gatsby v2. The docs had a process for converting a project from v1 to v2, but it looked long and tedious.

More searching led me to a potential problem in one of Gatsby's dependencies used for CSS processing. I easily wasted an hour trying to bypass that part of the build to no avail.

I want to take a moment to point out that somewhere in here would have been a good time to seek help from others. Finding a good place to get responsive help in working with Gatsby would have paid dividends both in getting a solution to my current problem and also in knowing where to go next time. I wanted to get the site finished quickly and I made myself feel like I didn't have time to wait for someone else to respond to my problem. I definitely think this was a mistake.

Inspiration

I don't know when it hit me, but I finally considered another solution: Instead of trying to make my v1 Gatsby starter work with v2, why not just use Gatsby v1?

I couldn't find documentation on the Gatsby website about how to choose an older version of Gatsby so it took me a while, but I eventually figured out the correct command to have npm install an older version of Gatsby. (In hindsight, I don't really blame the folks at Gatsby for this - if I'm going to use a tool like npm, I should probably figure out how to use it!)

Sure enough, with that done I was building my site and happy as a clam.

TL;DR

I think I've reached a good length for this post so I'm going to cover deployment of the site in another post - stay tuned! Before leaving though, here's what I learned about redesigning a web site (or building from scratch):

Use a static site generator and a starter template or theme. Build off the work of others!
Build it first! Sort out any problems before you start spending time on your own content.
Give yourself time so you can ask others for help. I wanted to GET IT DONE and gave myself an unhelpful time crunch that eliminated seeking help from others.
Enjoy the beauty of modern development tools!