Writing Course Notes

I haven’t posted a progress update in far too long. There are a million little reasons why, but I’m not going to get into them. Let’s just chalk that all up to “life happens.” What I would like to focus on in this post is course notes. What do my notes look like, how do I use them, why does it take me so long to complete a project when using it to create course notes, etc.

The purpose of my notes

First, let’s talk about what my course notes are and how I use them. I’m sure every content creator has their own process, but for me I like to write markdown files that I can basically follow along with when recording a course. This serves a number of purposes:

1. It keeps me on track.

When recording, it is really easy to get distracted. I might encounter a bug, tell a story, or my dog might bark (🐶 woof!). It doesn’t really matter what causes the distraction, the important thing is that I’m able to quickly get back on track. Notes really help me do that.

2. Notes help me organize everything

When I first started creating courses, I would find myself redoing videos with issues and while recording them I would think, “Oh man, I should talk about X here…” only to later realize I talked about X in the very next video and just forgot that it was already there. By using notes, I’m able to make sure every concept I want to teach is covered and I’m able to plan out the best place to introduce each subject before getting in front of the camera.

3. Notes will (hopefully) become ascii-casts

Railscasts has this really awesome tab in every screencast called “ASCIIcast”. In reality, it is just a short writeup of the screencast, but I like the name.

While many of my course videos do NOT have a written component, I like writing my notes this way with the hope that one day I’ll be able to turn them all into written versions of the video to make the content more accessible.

What do my notes look like?

Now that we know why I have notes, let’s look at what they look like. First, let’s look at notes from my testing course.

#### Tests that lost their purpose

Want to test:

```go
func DoStuff(inc Incrementer, n int) {
for i := 0; i < n; i++ {
inc.Increment(1)
// ...
}
}
```

First test:

```go
func TestDoStuff(t *testing.T) {
inc := MockIncrementer{}
DoStuff(inc)
if len(inc.IncrementCalls) != 3 {
t.Errorf("# of Increment() calls = %d; want %d", len(inc.IncrementCalls), 3)
}
}
```

Goal of this test?


In an ideal world - verify incrementer was incremented by `n`

Real wordl - verifying that we call Increment 3 times. WRONG

Sounds the same, but isn't.

What if we did `Increment(2)` or `Increment(n)`? Test fails, but shouldnt!

Happens when we "reverse engineer" code.

*It's a big reason why ppl advocate for TDD - you can't reverse engineer what isn't written.*

TDD isn't required though. We just need to focus on real goals. We need to test with a purpose.

"I want to verify that the incrementer is incremented 3 times."

Now our test:

```go
func TestDoStuff(t *testing.T) {
inc := MockIncrementer{}
initValue := inc.Value
DoStuff(inc)
diff = inc.Value - initValue
if diff != 3 {
t.Errorf("Increment = %d; want %d", diff, 3)
}
}
```

Subtle, but now impls can change and tests still do what they should do.

There are a few things worth discussing about these notes. First, they might seem like gibberish. My notes are written with only me as the intended audience, and they are written in a way that I can easily glance at them while recording and know what I wanted to cover next. This is done because I often record with my screen split into two sections: the top left where I actually record, and the right side of the screen which only has my notes (and audio monitoring tools I use while recording).

My desktop layout when recording with notes

The second thing I’d like to point out is that I’ll often have code samples right there in my notes, but in practice I have found that my final code looks exactly the same as that code only about 50% of the time. This code is really just there as a reference, so I know what I wanted to demonstrate and have something to fall back on if my brain goes blank.

Lastly, these notes don’t always cover everything in the video. I try to let the videos flow in whatever direction they take while recording, and this often means that notes are just a starting point. They aren’t a great representation of everything in the video, but they do represent every major point I wanted to cover when I started recording.

Writing course notes

Now on to the big question - why is it taking so long to create the new course backend?

The simple answer here is that I’m not just creating the course backend. I’m also creating course notes. For example, when I started setting up my React frontend I couldn’t just run npx create-react-app course-ui and start adding my dependencies. Instead, I had to write a big chunk of notes on:

  1. How to install Node
  2. Creating a React app
  3. Installing Tailwind and other deps I use

Here is just a quick peek into those notes:

# Getting React Setup

## Install Node

I recommend `nvm`: <https://github.com/nvm-sh/nvm>

This will have something like the following (but get the updated one from the website):

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash
```

Now run `nvm --version`

```bash
nvm --version # outputs 0.34.0 hopefully
```

Now install the version of node you want. I'm going w/ 10.16.0 which is stable and has LTS.

```
nvm install 10.16.0
```

This should get you `node`, `npm`, and `npx`.

If you opt for different version I can't promise things will work. The JS world changes far too quickly to say for sure.

What makes this challenging isn’t just the fact that I’m writing notes for everything I do, but I also have to break each piece of work into a small section that won’t leave your code in a broken state. This is especially hard when I would normally just install everything I’m familiar with, initialize configs, go customize each, then run it, but with my notes I have to make sure we have a small section on setting up Tailwind. Another on Postcss. Another on setting up our scripts in package.json. And so on.

And the crazy part? This isn’t even a JS course! I’m trying to teach “Advanced Web Development with Go”, but because this course has a React frontend I didn’t feel comfortable not covering some of those aspects and helping users get setup.

So yes, the course backend is taking forever. No, I can’t speed it up. But I promise both the new backend and the Advanced Web Dev course that comes from this process will be totally worth it 🤘.

Not all notes are the same

The last thing I want to mention is that not all notes are the same. For example, my Algorithms course (which I am still working on!) has notes that are more dense because I want an accurate description of the problem we are going to be solving, but they don’t include much else. This is intentional, because I want the video to include my thought process as I explore the problem and decide how to solve it.

## 07 - FizzBuzz [code]

Given a number N, print out all the numbers from 1 to N but when a number is divisible by 3 print out "Fizz" instead of the number, and when a number is divisible by 5 print out "Buzz" instead of the number. For numbers divisible by both 3 and 5 print "Fizz Buzz".

Sample:

N = 15

Output:

```
1, 2, Fizz, 4, Buzz, Fizz, 7, 8, Fizz, Buzz, 11, Fizz, 13, 14, Fizz Buzz
```

And now I’ll get back to coding so I can release this algorithms course before too long!

Learn Web Development with Go!

Sign up for my mailing list and I'll send you a FREE sample from my course - Web Development with Go. The sample includes three chapters from the book, and over 2.5 hours of screencasts.

You will also receive notifications when I release new articles, along with other freebies that I only share with my mailing list.

Avatar of Jon Calhoun
Written by
Jon Calhoun

Jon Calhoun is a full stack web developer who also teaches about Go, web development, algorithms, and anything programming related. He also consults for other companies who have development needs. (If you need some development work done, get in touch!)

Jon is a co-founder of EasyPost, a shipping API that many fortune 500 companies use to power their shipping infrastructure, and prior to founding EasyPost he worked at google as a software engineer.

Jon's latest progress update: Writing Course Notes

Spread the word

Did you find this page helpful? Let others know about it!

Vote on Hacker News

Sharing helps me continue to create both free and premium Go resources.

Want to discuss the article?

See something that is wrong, think this article could be improved, or just want to say thanks? I'd love to hear what you have to say!

You can reach me via email or via twitter.

Recent Articles All Articles Mini-Series Progress Updates Tags About Me Go Courses

©2018 Jonathan Calhoun. All rights reserved.