←
back to michaelgruen.com

Learn To Code by Working With Code

Building your Digital Zen Garden — a low-stakes, high-reward starting project for maybe not complete beginners, but close to it

(v.2024-08) August 11, 2024

“What should I learn first?”

“Start with git”, I said.

“Great! I’m downloading it now.”

Any educator reading this just rolled their eyes and has every right to do so.

What programming language should I learn first?

It’s as if someone said, “I want to learn how to paint!” and I said:

“Ok! First you need to find some canvas and a wooden frame, and then cut the canvas to size to stretch over the frame. Don’t forget the staple gun! Oh, also, do you have an easel, some gesso, sandpaper, and a lint-free cloth to prepare the surface for paint?”

My instincts to recommend git—software engineering’s canvas stretching—were directionally correct, but I failed to give context.

What follows is what I should have provided.

Zen Computer

Your First Programming Project

Project Motivation: Your Digital Zen Garden

Your first “learn to code” project will be a website that you create from source code, publish online, and keep entirely under your control.

Goal

The content is ultimately up to you, but I’d start with something you are already familiar with and care about. Ideas include:

Barring any of those (or a more interesting idea you come up with), the content could be a “learning to code” journal that recaps all the new languages, libraries, and tutorials you are using along the way. Use it to keep your notes and documentation. (If you hate it, you can always delete it later or make it private. Or change it. Or move it. It’s your garden, after all!)

Whatever you choose to make, this will feel very different than using website-in-a-box companies like Squarespace, WordPress, and Exposure where you trade your credit card for a service to do the “hard” work for you.

Quick note: this project involves putting content on the Internet and therefore making it publicly accessible. While it is exceedingly unlikely that anyone will find it unless you tell them about it, err on the side of caution. You can also always delete it. My hope is that you’ll instead continuously extend it, amend it, reinvent it… like I have with michaelgruen.com.

I’ve been working on my own for multiple decades. The elation of getting a computer to finally do the thing you asked it to do, or having software render the way you want it to, never goes away.

This project is a great beachhead for your journey.

Who is this for?

This project assumes a certain amount of grit and stick-to-itiveness. Just as Math Is Not Linear, neither is coding. Every tutorial, therefore, assumes some a priori and empirical knowledge. (Likewise, I don’t know who you are or where you came from, so the best I can do is send you on a mission with as much “heads up” on other topics you may need to learn on-the-fly.)

While autodidacts will probably fare best, this project is accessible to anyone who knows their way around a basic operating system (like Windows/MacOS) and is generally curious about how it all works.

It’s also important to remember that if anything goes wrong, there’s a 99.999% probability that it’s something that you did incorrectly. The computer isn’t out to get you—it’s just doing as it’s told. There’s enormous freedom in this even if it is, at times, frustrating.

You also need a computer with administrator rights and Internet access.

Why this project?

The goal is to build a meaningful and complete project with the opportunity to keep going as you follow your interests.

Key reasons to use this as a starting project include:

What you are not going to do in this project:

While you’re not going to learn everything there is to know about software engineering through this, you are going to learn a good amount about what it takes to create something and put it on the internet for all to see.

Project Overview

To create your website, you’re going to build and deploy what’s called a Static Website using a type of framework commonly known as a Static Site Generator (SSG). You’re going to put your work on a Content Distribution Network, or CDN, so anyone on the Internet can access your work if they know the URL.

Sounds easy right? Let’s get to it.

READ ME

I recommend reading through everything on this page (and on the linked pages within) at least once before getting started.

On that note, reading the README.md in the root folder of every software project you encounter will save you literal hours of headache later, so get in the habit now. RTFM.

If you get stuck on any step here, try to work through the problem for 3-5 minutes before seeking advice elsewhere. Read the error messages and try to work out what may be going wrong.

If you’re still stuck after re-reading these documents and starting/trying again, use your favorite LLM to help un-stick you. As of writing, Anthropic’s Claude 3.5 Sonnet is my tool of choice for coding support and it is very good at it.

Try not to rely on it too much. You’re learning. A bit of struggle is part of the process. Go slow now to go fast later.

If you’re still stuck, try explaining your problem to a rubber duck. (Yes, seriously.)

If you’re truly stuck, asking a software engineering friend for help or hiring a Codementor might be helpful. (While I occasionally use Codementor myself, half the time I end up realizing the issue while trying to explain it to my pair-programmer-for-hire. Seriously, try the Rubber Duck method first.)

Burn-down

Here’s what you’re going to do, in order:

  1. Generate a website on your computer using Hugo, a GoLang-based SSG
  2. Preview what the site looks like from your computer
  3. Edit the source code to see how changes affect the website
  4. Add a new page with your own content on it
    • (Don’t spend too much time to start… save for later.)
  5. Package up your progress to put on the web
  6. Change the content locally and deploy the changes
  7. Decide what to do next—repeat from step 2.

Skills for life

What you’re going to learn:

  1. How the command line works
    • (i.e., working with the command prompt, a “shell” for entering commands for a computer to “do”—a.k.a. “execute”)
  2. How to run a program from the command line
    • (i.e., running Hugo to generate a website and pages within it)
  3. How to edit and save source code
    • (i.e., using a text editor like Sublime Text)
  4. How to understand output files
    • (i.e., what your webserver uses)
  5. How to run a web server on your computer
    • (i.e., using Hugo’s built-in server to serve the output files in a way your browser understands)
  6. How to see your work locally
    • (i.e., viewing your new site locally from your web browser)
  7. How to version your work and revert it to a good state if you mess up
    • (i.e., using git for version control)
  8. How to publish your website on the internet
    • (i.e., using GitHub and CloudFlare to host your static site for free)
  9. How to extend your website’s functionality and keep it updated
    • (i.e., creating and editing source code that changes your site’s look, appearance, and content)

Programming tools and markup languages

You’ll gain exposure to all of the following, to a greater or lesser extent:

  1. The command line. MacOS and Windows have differing command lines, but either way you’re put into something called “a shell”. On the command line, you write commands that can be combined to complete a series of instructions. You’re just usually running them one at a time, but you can chain them together in sequence and do some cool stuff.
    • For example, want to sort a CSV (input.csv) by its second column in ascending order?
      In the command line, try –> awk -F',' '{print $2 "," $0}' input.csv | sort -t',' -k1 | cut -d',' -f2- > output.csv
    • Kinda neat, right? Super powerful, but kind of unwieldy. This is why we have higher order languages. But we’re not there yet.

  2. HTML. Hypertext Markup Language can barely be considered a programming language, but it does help describe how content might be organized on a page. Most people these days aren’t writing HTML directly. Instead, they’re writing software that generates HTML, or they’re writing in another structured way that enables other software to generate HTML. Such as…

  3. Markdown. Markdown is an easy-to-read, easy-to-learn “language” that can be easily transmogrified into HTML, which can show up on webpages. Or, it can be transformed into PDFs. The nice thing is that Markdown is also legible to humans who know nothing about programming or markup. Because of its flexibility and ease of use, it’s used almost everywhere within the programming ecosystem. Once you get used to writing it, you’ll find yourself wanting to use it everywhere since you don’t need to take your hands off of the keyboard, or remember which hot key works where in which application. It is also the format that most LLMs provide as output so you can copy/paste that content directly into markdown files for compilation into HTML.

  4. GoLang templating. If you’ve poked around the rest of the source code generated by the Hugo generator, you probably noticed the first of what is called control logic. These are instructions–source code–that describe how various parts of the HTML should be built, where to insert certain variables into an HTML page, and assemble different snippets of code so you can reuse code without having to retype it all. As you get into programming, you’re going to be spending a lot of time writing logic in a language suitable for purpose. (For example, markdown is a great language to write content in because it can be ported into other structured formats, like HTML, very easily. Similarly, trying to write HTML around your prose will become onerous really quickly.)

Your mission

Complete this tutorial, which starts by completing this other tutorial.

Yes, that’s it. (They’re not even my tutorials!)

Tips for Success

You might find the following content helpful.

  1. Learn to navigate the folder structures within your command prompt (Windows, MacOS). While you can use your mouse with Explorer on Windows and Finder on MacOS when working with files, you will need to use the command prompt sometimes as most developer tools are only accessible via command line. For this project, other than application-specific commands you’ll type into the command prompt like hugo server, the only command you’ll really need to know is cd which will help point your command prompt to the directory where all of the project files and applications live. When typed without arguments, cd will either tell you where you are (Windows) or take you to your home folder (MacOS). With arguments (e.g., cd /the/directory/path) will take you to /the/directory/path. (If you want to know where you are on MacOS, try pwd for print working directory.)

  2. Pick a folder to start working with. On MacOS, I like to put all my coding work in a folder off of my user folder, like so: /Users/(yourname)/code, or ~/code. On Windows, you can create a new folder in My Documents and work out of there.

  3. Accept the fact you’re going to need to learn git and get it working on your computer.
  4. Unless you already know how package managers work (e.g. homebrew, chocolatey), opt to download the application (a.k.a. the “binary”) directly to the working folder instead of trying to learn this now. (Add to your “future learnings” todo list.)
    • Find the “Extended Edition” for your operating system (the file name will start with hugo_extended_, and look like hugo_extended_0.131.0_windows-amd64.zip where 0.131.0 happens to be the latest version number at time of writing, and windows is your operating system. Version number might be different. Not important. MacOS users, yours says darwin-universal instead of windows.)

  5. When you’re trying to run hugo for the first time, your operating system may ask you to “trust” the application before you can run it. As of writing, Hugo is perfectly safe to run on your system despite any warning, and is very unlikely to contain future vulnerabilities that would affect your computer’s security profile. Don’t worry about it.

  6. Download a text editor. Not a word processor. You will eventually find yourself in a holy war here about which text editor you should be using. Unless you’ve been indoctrinated in the great text editor holy war, I recommend you download and use Sublime as it is free to use, easy to install, and is probably the most accessible text editor for newbies.
    • ‼️ Do not use Microsoft Word, Apple Pages, Google Docs, or any other word processor, even if it’s what you are “used to”. These applications are not text editors. This route would be foolish.

Setting Expectations

Why Hugo?

  1. It’s not JavaScript (save that ecosystem cacophony for later).
  2. It’s fast: tight feedback loop between changes and results with good error messaging.
  3. Low risk of computer havoc. Other than the downloadable application (“executable”), there’s nothing else to configure.

Key Paradigms to Note

  1. WYSIWYG vs Page Generation: Unlike most things you’ve probably done on a computer, what you type isn’t directly what you see. There’s a “processing” bit in between the text you write and how it’s presented to you after a generative step. (Hugo rebuilds the entire website for you in milliseconds every time you save a file, making the feedback loop tight. Not all SSGs do this well.)
  2. Source Code vs. Generated Code: The code you write isn’t the same as what the computer uses or what the user sees. It’s put together on the fly. While you’ll write your content in Markdown, Hugo will transform that markdown content into HTML, using the templates and themes in the form of template source code.
  3. Compiled Applications: While Hugo is an application you downloaded that generated a bunch of website source code, the Hugo application’s source code can itself be viewed. Hugo is what’s called a “compiled” executable. This is beyond the scope of this tutorial, but if you want to take a look at its source code for future exploration, it is available here.

Embracing the Challenge

The developer experience has improved dramatically over the years. With LLMs and improved tools, there’s never been a better time to learn programming.

However, facing challenges is an integral part of the learning process. Do not deprive yourself of it! Take your time to figure out what’s going on. When you encounter obstacles, try to work through them using the resources provided earlier. This problem-solving process is where much of the learning happens.

What’s next?

This section will provide some context as to what you’re working on and where you can go from here.

There are a few ways to proceed:

Try another SSG

First, you can try doing the same thing using another SSG with a bit more of an involved programming language, like Node.js and/or JavaScript. This would mean dropping Hugo.

Gatsby was my go-to years ago, but this ecosystem has grown significantly—there are now 335 SSGs available for you to use, all with different plusses and minuses. I haven’t tried this, but my next stop after Hugo would likely be Docsify as it uses vanilla JavaScript and does not use React, which would be a whole new thing to learn.

Whatever you might choose, the important thing to note is that the markdown is transferable. You can reuse your content while swapping out your entire site generation engine.

Neat, huh?

Get fancy with CSS

Or you can start learning about CSS. CSS, Cascading Style Sheets, is a way to instruct how the browser should interpret various HTML elements. (This is also transferrable between SSGs, albeit more involved.)

Most people don’t write pure CSS anymore. Instead, they use a meta-language such as SCSS (pronounced “sass”), a library (like “Bootstrap”), and/or a framework like TailwindCSS (currently very popular in the industry). No matter what you use (or what the SSG defaults to), it outputs to CSS all the same.

Experiment with JavaScript

Maybe you want to start trying to write some JavaScript to have some custom things happen on your webpages.

One of the nice things about JavaScript inside of SSGs is that you can use it to decorate and accessorize your website. It’s a great way to experiment with how your users interact with your site before complicating it with a server, filesystem, and/or database.

Integrate Third-Party Services

The next thing I’d look to do is integrate with some third-party service to see how that works. An easy way to start is to try and add Google Analytics so you can understand how users might use the site. Or, you can implement a user email list signup by embedding a webform that saves to a third-party email service. (Mailchimp is a popular choice for small to medium businesses, but there are many options.)

Publish Your Work

Once you’ve messed around a bit, I would encourage you to start again and then move to publish something on the web, if only for the experience. Just because it’s publicly available doesn’t mean anyone is going to go looking for it.

Learn Git

Git is a powerful way to snapshot your work in time. No longer will you need to have Final_Paper1-final_FINAL2.docx as git can version-control this all for you.

You might find git challenging at first. Really. But you’re going to need to learn it because it’s what everyone (well, nearly everyone) uses. And even if they don’t, they still know git.

Learn About Abstractions

All software runs on layers of abstractions.

Working with code takes you out of user-space (where you click, tap, drag, scroll, proto-code) and introduces you to some of those layers. My suggested project works with layers 3-7 of the OSI model—how computers talk to each other—as well as some of the basic inputs and outputs using your very own computer’s von Neumann architecture, which you’re already very familiar with as expressed through your device’s graphical user interface.

No programmer I’ve ever worked with knows the entirety of these architectures by heart as the whole of computer programming is way too large to fit in anyone’s head all at once. (This is one of the reasons I’m excited about generative AI and how they shift team cognitive requirements.)

This is all to say, know that these abstraction layers are there, but there’s too much to worry about all at once. So don’t worry about it too much until you know how to worry about it.

And then decide what part of it you want to worry about and learn it.

Go Deep

Launching something goes broad, providing you with a sense of how everything works together. Once that’s running, it’s easy to extend it. Follow your interests. Go deep.

For my money, there’s more to learn in launching a functional piece of software and adding on to it than in speed-running sandboxed, web-based tutorials.

If you can find a tutor, a classroom, a managed experience, or a self-directed course, that’s great too. Consider it supplemental. It is notably more empowering when you can do something real and useful. Coding is always a bit of a challenge, so it’s better to get comfortable with that reality early. Recognizing this, more experienced folk are generally very willing to help unstick you, especially when you’ve tried your hardest to unstick yourself first.

Better to get one’s hands dirty.

Scroll back up and get going!

Additional learning opportunities

Once you have a better idea of where you want to go with your learning:

When you need help:

Programming YouTube Channels that I subscribe to:

Glossary

term description
Stack Trace A readout of the program’s memory construct, usually generated automatically in a long, cryptic blob on programmer error.
USENET A decentralized discussion system populated with nerds inventing stuff. (Wikipedia)

←
back to michaelgruen.com