DEV Community: Tatiana Mac

Beginner's Guide to Eleventy [Part II]

Tatiana Mac — Tue, 19 May 2020 12:49:13 +0000

Welcome to Part II

You are reading Part II of a IV part series.

Part I: What is a static site generator?

Part II: Installation 👈🏽 You are here

Part III: Structure/Basic Customisation (coming soon)

Part IV: Advanced Customisation (coming soon)

If you are confused or in need of context, please go read Part I—it is where I establish all the context of what static site generators are.

As much as possible, I'm going to treat this part of the tutorial like a cookbook, except I won't make you read seven paragraphs about that one summer I spent in Emilia Romagna rolling the perfect tortellini as I had a torrid tryst with Paolo (sorry, reading too many romance novels).

I will, however, tell you all of the "ingredients" you need, dirty my hands with the scary parts, take it step by step, and ensure that I provide ample resources to prevent you from hitting dead ends.

Let's collectively admit something: We are not great at giving robust and clear installation instructions. More often than not, our package installation instructions look something like this:

Installation:

npm i luigis-castle

You're set!

I'm sorry, what? Where do I... put that? Then, what? Even if I know where to put that, I now have this cyborg telling me that I'm missing several trillion dependencies? I'm sorry, are you telling me to go to therapy? I already do, and therapy is awesome, sucker.

I want to prevent that.

So, you might find that this guide is --verbose. It is intentionally so because most of the time we're overly concise and people give up at the very beginning. I've partitioned explanations into notes where I can, so you can choose to skip over them if you already know everything. Cool? Oh, you want a cookie. Here. 🍪

Let's get started.

Tools Required for Eleventy

A developer's tools can be personal. To some degree, if you choose well for you, a tool can really help speed up rote tasks, give you fewer headaches (by providing more colour customisation and modes), and create a more pleasant developer experience (DX).

Some developers have strange infatuations with tools and will insist some are better than others—10x developers might even make fun of you if you use the wrong tools. I think it's more personal than that. Picking out dev tools is like picking out a sports bra. Try out a bunch. See what sucks the least for you that you can get in and out of without breaking your arms. Learn how to customise them so you're less likely to have a uniboob. Abandon them in the back of a drawer if they don't work.

1a. Terminal Emulator

Terminal emulators (or Terminal or Term, if you're friends) are the bare bones text tools that make you look most like a hacker. If you've ever opened up Windows Terminal on Windows or Terminal.app on MacOS, you were in the terminal emulator. Terminal emulators are essentially stripped-down programs without much of a visual interface that can give you access to your own computer and connect you to other computers.

Inside of the terminal emulator, you are using the Command Line Interface (CLI). When people talk about running something in command line, this is what they’re usually referring to. By comparison, most programs that we use day to day, like Microsoft PowerPoint, Adobe Illustrator, Sketch, Microsoft Paint, are all considered Graphical User Interfaces (GUIs). In GUIs, you can see a visualisation of what you're doing. When working in a CLI, you are using text commands and relying on text output, which can be harder for many to visualise. We’ll talk more about this later, but as with all things, your preference for CLI versus GUI (when both exist) is up to you.

Terminal emulators can do a lot, but for the purposes of this tutorial, you'll mostly be using it to download and to run Eleventy, to manage your packages (heh), and to version control your code.

Examples: Hyper, iTerm2, Terminal (default for MacOS and Windows).

Cues : Many tutorials are not always explicit about when you're using the Terminal. Usually if you're cued to run, build, npm, npx, homebrew, yarn etc, and you see a short block of text like this, often preceded by a $ (which you should not copy):

$ npm i make-me-a-sandwich-mario

You're going to paste that in your Terminal and hit return/enter to run it.

1b. Shell Language

When you run scripts and commands in your terminal emulator, you do in a shell or command language. The default language for Linux and older MacOS (pre-Mojave) is Bash and newer MacOS is zsh. The differences in the language usually result in the commands differing slightly.

I mention this here because this is a future potential "gotcha" where you can get slipped up because an installation guide for a package manager can presume you are using one or the other. While they are very similar, there are slight differences that can cause headaches. It's important to know which you're using and general differences.

If you have never interacted with your terminal's shell language, I recommend figuring out which is your default. To do so, open your terminal emulator, and run (paste in this code and hit enter/return) this command:

ps -p $$.

It should return (send you back) something like this below:

The command ps is telling the command line to show all the processes that are running. The -p flag tells it inform more about the process, and the $$ tells it to narrow this down to the current process.

If you see zsh, bash, tcsh, ksh (anything ending in sh), that's your shell language. (If that didn't work for you, try some of the other commands.)

1c. Installing Node.js and npm 📌

Node is a environment you need to install onto your computer in order to run Node Package Manager (npm). (You need npm to install Eleventy—the whole point of this post. Did you forget? I sorta did!).

To check if you already have node on your machine, run the following command in your terminal emulator:

node -v or node --version. (If one doesn't work, try the other).

You may have noticed that sometimes flags have one hyphen and other times they have two. One hyphen flags (-v) are the short-name version of the command, and two-hyphen flags (--version) are the long-name version of the command. I find that when I'm starting out, I like to write out the long-name/two-hyphen version so I can talk myself through what I'm doing.

If it returns v followed by numbers, something like v12.13.1, that means you have Node installed. Eleventy requires any version of Node newer than 8, so if you've got that, you're set! Woohoo!

If you get anything other than that, that means that you either don't have it on your computer and will need to install it or need to update it.

Follow the instructions below for your operating system, and come back here once you do.

For MacOS.

For Windows.

Once you have Node.js installed, you can now install npm.

1d. Installing npm 📌

npm is the main package manager for Node.js; they have a registry of all the packages and modules which is accessed by a command line interface. Think of it as the central library of code snippets that everyone can "borrow" at once. npm makes it so that you can search for specific features you need to add, like a React image carousel or a static site generator, like Eleventy!

Packages can rely on other packages, which is called a dependency. You will come across that word a lot. A dependency means that a package (let's call it House Package) uses another package (let's call it Room Package). Sometimes, when Room Package makes an update, it can break House Package. Sometimes the maker of Room Package decides to remove it from the registry or make a change that isn't compatible with House Package. That means House Package can break. Now imagine this incepted from House, into Street, Neighbourhood, into City, into State, into Country, into Continent! One small change can impact many pieces of software, and frankly, take an entire sector of software down. So, it's important to be mindful when you're engineering of all the dependencies you invite in, and to monitor them.

If you installed Node.js, then you should have npm installed. To check which version, in your terminal emulator, run:

npm -v or npm --version. (If one doesn't work, try the other).

At time of writing, the current version of npm was 6.14.5. If you have something older, update your npm by running the following command:

npm install npm@latest -g

2. Source-Code Editor

A source-code editor (or just code editor if you're friends) is where you edit code or make the magic happen as I like to say. The code editor is also where you can look like a hacker.

Choosing a code editor can be really daunting, as everyone who has a four-letter name has a strong opinion about which is the best and is willing to go to great lengths to convince you.

If you're starting out with code, my recommendation would be to pick the one that stresses you out the least. Look at the screenshots and read reviews. Consider what customisations are for your needs, say, like if you rely on a screen reader. See what seems appealing to spend hours crying in front of. For many years, I wrote in Coda (RIP), Sublime Text, Atom, then now I'm in Microsoft Visual Studio Code (VSCode). However, I think if I started in VSCode, I would have been overwhelmed with all the bells and whistles.

Examples : GitHub's Atom, Adobe's Brackets, Notepad++, Sublime, Vim if you hate yourself and wear purist badges proud (jk! No tool shaming), Microsoft's Visual Studio Code (VSCode)

Cues : If you see longer blocks of code, you're going to likely edit that in your code editor.

You might hear someone refer to their Integrated Development Environment (IDE). People sometimes use IDE interchangeably with code editor, when they are not, in fact, interchangeable. By definition, IDEs comprise a code editor, build automation tool, and debugger. Sometimes they have GUIs integrated into them as well.

Most tools you hear about are code editors, including Microsoft's Visual Studio Code (VSCode or just Code if you're good friends), which, while robust and very full-featured with the help of extensions, is not an IDE. Microsoft's Visual Studio is their IDE, as it is a fully-integrated environment. Naming, am I right?

Also, because people tend to get their panties wound up in sailors' knots about this, you're not any "less" of a developer for using either a code editor or an IDE—use what you like and change it up if you change your mind. Neither is intrinsically better than the other; they're both valid for different developers in different contexts. Some IDEs and code editors have better support for certain languages, for instance. That's the sort of thing you should note for how you decide, not what some Chadwick tells you to decide. I've articulated the difference here for the pure purpose of education. And, as someone who writes and runs a dictionary, I think nuance is important. 🙂

For the purposes of what we're doing, I'd recommend that you get a code editor as it will suffice for this project.

3. Browser 📌

You probably already use a browser regularly. In fact, I would be willing to bet you're accessing this post from a browser. However, the browser that you use day to day to surf might be different than the one you choose to use when developing.

While we should all test our sites across multiple browsers, I think most of us will conduct the majority of our build within the browser we feel most comfortable with initially. To me, the choice of what main browser to use to do the majority of my development comes down to what the audience is most likely to use (this is one of many areas where user research is critical!). If no compelling user-driven decision exists here, like if it's for my personal site, where I don't collect user data, it typically comes down to the Developer Tools and Extensions I care most about.

Personally, I use Firefox equipped with DuckDuckGo as my search engine for most of my browsing (because security and privacy are very important to me for personal browsing), but I recognise that's a small user share. I sometimes use Firefox Nightly so I can take advantage of cutting-edge features. (Firefox Nightly is not stable, though, so it's only used for this purpose). I develop primarily in Firefox and Chrome. (I prefer Firefox's DevTools and Chrome performance tooling [Lighthouse]. Play around with the Developer Tools of multiple browsers. See which one's interface makes the most sense to you.

Examples : Desktop : Brave, Google Chrome, Microsoft Edge, Mozilla Firefox, Apple Safari, UCBrowser, etc. Mobile Google Chrome, Opera, Opera Mini, Apple Safari, Samsung Internet.

4. Git 📌

Git is an open-source, free distributed version control system. Git enables you to take snapshots of your code, so that if you break it, you can revert to when your code was functioning. It's like the Delorean for code. It also allows you to share your code for collaboration, for multiple people to work on the same code without saving over each other’s work. It also allows for you to share your work, for someone else to download a copy, and to play around with it.

When you think of Git, you might think of BitBucket, GitHub, or GitLab. Technically, all those products offer Git hosting as a service; providing storage to the code somewhere where many people can access—this is the underpinnings of what it means for the version controlling to be distributed. Git hosts also often a whole host of other benefits, like helper tools (a desktop GUI or web interface that visualises what’s happening in the command line, for instance), allow you to create profiles, and find new projects and collaborators.

Git can be accessed from a emulator, a desktop GUI, a web app, and is integrated into some code editors/IDEs (and a combination of four three). Most developers primarily rely on accessing it through their terminal emulator, as GUIs can be limiting (and not all Git hosts offer them), but I highly recommend you try them all and see what works best for you.

Git is without a doubt one of the most intimidating parts of being a developer. For visual folks, it can be hard to understand what is going on under the hood. Git commands are sometimes obtuse. Working on massive code bases with large teams can exacerbate these fears.

Git is something that generally becomes more intuitive as you practice. Practice, practice, practice. I recommend using it on your own small projects. Allow yourself to make mistakes and learn how to get yourself out of them. OhShitGit is one of my favourite resources for when I get stuck and feel that git-sweat come on.

And, though practice helps, know that even the most seasoned developers royally fork (SORRY) up their repos sometimes. It's okay. It's this weird thing we all do so we can commiserate over it, like burpees or taking out the trash. Most things you do are reversible. If you're worried at first, there is no shame in copying your entire folder somewhere else just in case. There's a saying about something not being backed up unless it's backed up thrice anyway.

For the purposes of this project, you need to have git installed onto your machine and an account with a git host.

Installing git can become complicated and frustrating very quickly. If you encounter roadblocks, know that you're not alone. While I'd love to explain exactly how to install git, several key factors will change the exact instructions, including the operating system you use (MacOS, Windows, Ubuntu, etc), what command line interface you use, etc. Atlassian’s guide is a good place to start.

Examples of Git Hosts : Atlassian BitBucket, GitHub, GitLab, SourceForge.

Note that for most personal purposes, these services offer free accounts. Be mindful of what constitutes as a paid account and for what needs.

Installing The Things

Once you have your terminal emulator, code editor, git installed, and an account with a git host, you're ready to install Eleventy! You've made it past a huge hurdle! Seriously, not being sarcastic. Environment set-up is one of the biggest hurdles, and you just did most of it!

The last step is installing Eleventy.

In your terminal emulator, run pwd (present working directory) (if that doesn’t work for you, try cd) to figure out where you are. Once you are where you think you need to be, run ls (shortened form of “list”) to list out all the items in the folder you are in (or dir for Windows).
Navigate to the folder you want (use npm to go into a folder; use cd .. to back out of a folder). (Note that depending on your operating system, the back slashes () could be forward slashes instead (/).
Once you are in the folder you want to house your project, run mkdir \eleventy-project-name\. (You can call your eleventy-project-name whatever you want. It’s not permanent, and we can change it later.) mkdir creates a new directory with that name.
Navigate into that folder using cd \eleventy-project-name\
Run npm init -y. This command creates what's called a package.json file; they are like a recipe of all the ingredients (or packages) used from npm. Package.json files can also keep track of other on-going tasks that your project needs. When someone clones your project, the package.json file tells npm all of the packages that are necessary to make that project run. The init initialises npm. The -y here is saying "yes" to all the questions that npm asks, and sets them to defaults.

The command line should return a confirmation that starts with "Wrote to [directory]/package.json: ...more code".

Run npm install --save-dev @11ty/eleventy.

install goes to the npm registry and asks it to look for @11ty/eleventy. --save-dev tells npm to save this package (@11ty/eleventy) into what's called your devDependencies. All of this is happening locally, which means that this Eleventy install will only work for things inside of this directory.

Unpacking that further:

devDependencies are what are required to develop your package and are installed automatically when someone downloads your package. Dependencies are what is required to run the project, so for example, a user of a package needs its dependencies, but not necessarily its devDependencies. Your package.json is what keeps track of all these packages you use.

The --save-dev command is what tells the command line to store this into your devDependencies in your package.json file. The two dashes that precede the words save-dev command into a flag. So, when someone says “add a save-dev flag,” this is what they’re referring to.

While you read all that, you may notice that npm is still running. You should see a sort of progress bar to let you know how much more it has to go. You may see a series of warnings about things that have been deprecated. For now, you can ignore all that. (Most developers continue to ignore all that.)

Whenever you see a -g flag appended to an npm command, that means that it’s going to be installed globally. The upside is you’re only going to install it once, but you might run into issues down the line. Most folks work locally, as it prevents what are called “interoperability” issues. For example, you might encounter a project that is running on an older version of Eleventy than the global one you have installed, which will cause infuriating errors. Therefore, it’s best to treat each project independently. You might notice that most devs prefer to install things locally for this reason.

To check that Eleventy installed properly, run npx @11ty/eleventy.

npx is a helper tool for npm. If you were to run npm @11ty/eleventy, it would not work. The reason for this is a bit complex (Kat Marchán, who authored npx, explains npx in this Medium article.), The general reason is that npx will check your global folder to see if the package you want to install already exists. If it doesn’t, it will go ahead and download that package locally and run it for you, which saves a few steps and prevents you from future headaches. (Read more about why local installations are preferred above.)

The command line should confirm that Eleventy is installed by returning something like:

Wrote 0 files in 0.03 seconds (v.0.11.0).

Because you haven’t written any files yet, it makes sense that there are 0 files to write. The v… indicates what version of Eleventy you are running. At time of writing, it is v.0.11.0

Now, we are going to create an index.html page so you can see Eleventy in action!

Run echo 'You are officially a developer!' > index.html

Breaking this command down, echo says to the command line “read me back all this stuff.” Everything within the single quotes (‘) is what you’re asking the command line to read back.

The second part of the initial command, > index.html, includes what is called an append symbol (>). While you might know this as the greater than symbol, in this context, it tells the command line to instead place (or append) the stuff inside the single quotes into a file called index.html, instead of returning it, like the compliment it did above.

The command line won’t confirm that it successfully created the file. It will just start a new line and await the next command.

To view your work, you will now run Eleventy again by typing npx @11ty/eleventy. OR, you can push the up arrow on your keyboard until you see that line again and hit enter.
Now we want Eleventy to show us the work we did in the browser by running npx @11ty/eleventy --serve. You’ll see it run a few commands and end with “Access URLs.” Copy and paste the http://localhost:8080 into your browser. You should see your site that says “I forking did it!!!” because you did!

The --serve flag takes your files and opens them in your browser.

As we learned about in the last post, this step is where Eleventy takes all of the static files in all their different languages, and generates the site into languages that the browser can render. We'll talk more in the next installment of the structure of Eleventy and how this all comes together. For now, know that this is the part where the Generator part of Static Site Generator comes from.

Feel boss! You have gotten your environment up, and have a fresh new website to play with! You are totally a developer who served up your first static site (Or maybe 30th! It’s still exciting!).

Thank You

Thank you to Dia Trahman, Eddie Pearson, Jennifer Davis, Melissa Em, Sunil Pai for their attention to detail, in particular, for the beginner readers who bravely went through my imperfect instructions!

References

Wikipedia: Usage share of web browsers

Questions and Corrections

For questions, please reach out on Twitter! I can't promise to answer all your questions, but I'll try my best!

For corrections (typos, factual inaccuracies), please file a GitHub issue.

Our Ugly Middles

Tatiana Mac — Thu, 02 Apr 2020 16:09:03 +0000

Dear Developer,

I want you to hug your ugly middle.

No, I wasn't insulting your body. I want you to embrace the concept of the Ugly Middle. You might know it. The Ugly Middle is that part after the high of the Shiny New Thing has worn off and before the excitement of The End hits.

In Corporate Work: The Ugly Middle is when the project is most likely to fail; where the aspirational criteria hit the reality of API limitations, when engineers have been pulled into too many directions, and when lofty and unclear leadership plans mean one too many pivots.

In Personal Work: The Ugly Middle is when the project is also most likely to stall out; where the excitement of starting our own portfolio in a new framework has worn off when our big aspirations for customisation have hit the rubber of the Documentationless Road, where our enthusiasm has been met with our old friend, Imposter Syndrome, and we realise "wow, copywriting is really hard."

While The Ugly Middle is decidedly Not Fun, it can provide us with valuable lessons in resilience and acceptance and teach us how to stop the quest for perfection, particularly for the work we do for ourselves.

Completion is Arbitrary 📌

I think that chasing the high of completion is a fallable hunt. When is something really done? It shouldn't be, as it's likely that we've forgotten something. Usually, and unfortunately, that thing is probably accessibility- or performance-related (as evidenced by WebAim's The Majestic Millions 2020 update, where things got worse. I mean, we knew 2020 sucked more than 2019—here's how we made websites suck too! 🙃).

Perfection Kills Progress 📌

The longer we spend in the Ugly Middle, the more time we can iterate and improve. Searching for perfection does one of two things:

We stop ourselves in our tracks from imposter syndrome, and never finish; or,
We put out what we think is perfect and think we're done.

Both are problematic, because both involve stopping (unintentional in one, intentional in the other). One incapacitates us from moving out of abject fear that we'll fail, the other arrogantly, perhaps, thinks that failure isn't a possibility.

What if, we instead, recognised that failure is inevitability and one we can embrace. If we build the concept that we don't ever plan to stop, it gives us room to Err , to Forgive ourselves, and then to Fix it. The EFF This Cycle, we'll call it.

Embracing this cycle allows us to constantly improve and move forward. The increments they may be small, until we realise that incremental progress is better than none. Slow and steady wins the race, the tortoise reminds us.

Stop letting your fear of the ugly middle, driven by your impossible search for perfection, stop you from starting or continuing. To allow ourselves this, we must allow ourselves to ship things that we recognise will not be perfect. I recognise that some people will find this unacceptable.

I dare those people to show me something that's perfect.

Perfection, I humbly think, is nothing more than a standard set by whomever is in power. The entity in power might just be social structurally set (like, Western standards for beauty or cleanliness, as one example), but it's always there. Perfection for me is not the same as perfection for you. We're chasing the impossible.

If we accept things at their Ugly Middle, and build in a mechanism for feedback and ways to improve, we're shifting our focus from the ethereal in the distance to the step immediately before us. I'd like to think the more we do that, the less imposter syndrome that we would have.

My Ugly Middle 📌

To eat my own dogfood or whatever (aside: I find that to be the most disgusting analogy—why are startups eating dogfood?), I want you to know that as much as I love this here personal website of mine, I know that there's a dumpster fire about to burn a house of cards down. The things I'd like to fix (which I should remember to migrate to GitHub issues, I digress):

The accessibility isn't perfect. I know that accessibility wonks will run the same audits I run for clients on my site and be like "gotcha!" And yes, you gotme! I know of plenty of fixes that I want to make, and there are plenty more that I'll eventually learn.
The code is messy, both figuratively and literally. I see this somewhat as a sandbox, and as much as I believe in validated code and ensuring things are to standard, I miss things sometimes.
The design system broke down when Performance Tatiana went ham on the code and Designer Tatiana tried to add some new fonts without really considering all the design impacts. It pains her that the padding is inconsistent across pages and modules.
There is a LOT of unused code, which I'm reminded of everytime I run Lighthouse and look at all the unused CSS.
I have approximately 943,349 ideas that I want to write about and never enough time to do it. You'll find abandoned branches by the side of my Repo Road, all desperate for me to pick them up in my Code Camaro—what wait are we talking about?

The point is: I love things to be good and right but my shit isn't perfect. And some of you still seem to think it's worthwhile. So I let it be. Something here to represent me is better than nothing here to represent me.

Permission Granted 📌

I'm giving you permission, Developer, to launch your site when you know that there are accessibility improvements to be made or if the content causes horizontal scroll, so long as you promise to prioritise investigating ways to fix it. I'm giving you permission to ship a little too much JS (as a treat), so long as you promise you'll find ways to shave of a few KB each time you touch the code. I'm giving you permission to have spelling errors, so long as you promise you'll spell check as much as you can.

Most importantly, I'm giving you permission to be and to make enough, so long as you build in a mechanism for people to give you the feedback and for you to take the feedback seriously sans fragility.

I ask, in return, that you give some grace to other people and their work. When you find something wrong or incomplete, provide space for context you don't have. Find ways to be helpful instead of hurtful. If you must get angry at something, get angry at infrastructures that make it harder for us all rather than at each other and find ways to dismantle those infrastructures. If you don't have energy to help, then simply step away. If you have the energy to call it out, then you have energy to do so helpfully. We are not burdened to fix everything, nor can we, nor should we try.

Whether we admit it or not, we're all at our Ugly Middles—some day uglier than others—just trying to make it to the next commit, the next day, and the next challenge ahead.

Beginner's Guide to Eleventy [Part I]

Tatiana Mac — Thu, 02 Apr 2020 16:09:03 +0000

Intro to the Series

I won't lie. When I first installed a static site generator (SSG), I was pleased with how quickly it installed. However, my immediate success was short lived. Something something, beginner's luck.

Even though I was comfortable working in design and templating systems (having built many WordPress sites before) and competent in front-front-end development, I still wasn't clear on a lot. I couldn't understand how pages were rendered, where assets and data were stored, and really, how this was saving me any time at all?

My learning curve was steep.

Like any good developer, though, I hate myself, so I stuck with it. Bit by bit, I learned the power behind the simplicity, flexibility, and reproducibility.

My hope with this guide is to remove barriers, particularly for designers/developers who:

are limited by What-You-See-Is-What-You-Get (WYSIWYG) tools like Squarespace;
want the efficiencies of a content management system (CMS);
possess some competency in front-end languages (HTML, CSS, JS); and/or
don't understand the basic setup and infrastructure of SSGs.

To remove barriers to entry, we must provide adequate context. I will break this guide into a multi-part series:

Part I: What is a static site generator? 👈🏽 You are here
Part II: Installation
Part III: Structure/Basic Customisation (coming soon)
Part IV : Advanced Customisation (coming soon)

In general, I think our industry fears overexplaining concepts. We tend to presume people have skills that they don't always have and leave a lot of helpful context or explanation unsaid. After "hello world" examples, we tend to optimise our content for superusers. Beginners are sent into the world with a very limited foundation and asked to make a fairly large leap to intermediate on their own. By writing more beginner-through-intermediate tutorials like this, I hope to provide a solid foundation by answering unanswered questions and escalating examples as we go.

Throughout this tutorial, I will simplify some things a little bit (like in diagrams), which means you could "well actually technically" me and be right. In other areas I will be intentionally verbose, which means I might explain concepts you already know. Congratulations. Here is a trophy. 🏆

Part I

Before we dive into the tactical how-to (which you will find in Part II, once I write it), I want to provide context for static site generators (SSG) and how they fit into the web landscape. I'll break down what the fork an SSG even is (not a Star Trek series as I once thought), how SSGs compare to other tools and frameworks, costs/benefits to this choice, and lastly, why I choose Eleventy for my own site.

The Landscape

Generally speaking, there are two types of sites:

static sites and
dynamic sites.

SSG-generated sites are technically a subcategory of static sites, but they're a special type. More on that later. Dynamic sites include sites built atop a framework, like WordPress, Drupal, Joomla.

Static Sites

Static sites have static content. Static sites store the information (or assets) needed to serve the site (HTML, images, scripts) on a server (usually whomever is paid to "host" the site).

When users access a site in their browser, the browser requests files from the web server.
The web server gathers the files you need for the specific page you requested from a finite list of files that it has stored.
The web server sends the files to your browser.
Your browser renders the files and presents you with the website.

Theoretically, everyone should receive the same information (even if it ends up looking slightly different).

The first website launched in 1990 by Sir Tim Berners-Lee was a static site with just unstyled HTML.

Static Site Examples

Static sites are most any site when we think of "basic" or "hard-coded sites" (though those are not the only ways to generate static sites; more on that later).

I wanted to add a list here of static sites built by hand (without the assistance a static site generator, framework, or platform). If you come across any good examples, please reach out on Twitter so I may add them!

Static Site Pros

Fast : Static sites are predictable. Because there is a finite list of requests you can make (get me this page or that page), there isn't any processing that happens on the server side. The more requests you can make as a user that require the website do something, or client-side server requests, slow down a website, particularly when they become complex. Client-side server requests things like when you search or filter a website, or log in.
Lean : Static sites aren't as resource-intensive (their file sizes tend to be relatively small). If you have an unexpected spike in traffic to your site, they are usually able to handle the influx just fine (as long as their web hosts are able to keep up).
Secure: As there are no entry points (you can't input or send information to a static site like you can in dynamic sites), static sites are much more secure when used for a comparable dynamic site.
Economic Hosting: You're usually just paying for the hosting of your static assets, which is inexpensive compared to dynamic sites that require maintaining a service (like Squarespace) and a database (which involves things like mySQL).
Controllable: With a static site, whoever creates it has a lot more relative control over the source files. Since the source files and the rendered files are the same, you know how the site will be generated.

Static Site Cons

Note that there are workarounds for many of these cons. For scope of article and brevity, I've left out the tools that address/serve some of these cons. I know they exist. Some of them will be addressed in the SSG section, so hold your commenting horses (ya neigh-sayers), and note that I can't talk about everything in this one article.

Limited : Static sites can't do more complex things that we take for granted, like buying things online, getting weather for our location, etc.
Gatekept: Static sites require knowledge of HTML/CSS/JS to create and to update, turning developers into either content overlords or servants (depending on your org structure 😂). If you don't have these skills in house, you'll have to source them. Hand-coding websites is time-consuming, and thus, can be costly.
Non-dynamic: Everyone receives the same content, regardless of things like geolocation, time of day, etc. (Here is one of those areas where workarounds can apply. Did you stop yourself from explaining to me? Here, have another trophy. 🏆 Don't forget to unwind your undies.)
Difficult to scale: Depending on how you built the site, updating one global element (like a navigation) could mean updating hundreds/thousands of pages, which is impractical, resource-intensive, error-prone, and... boring AF.
Inconsistent: Consistency is reliant on the people building and maintaining the site. If they are not meticulous and/or lack adequate resources and quality assurance infrastructure, the site will likely lack polish.
Inputless : No log-ins (accounts), inputs (forms), or user-generated content.
Not Version-Controlled: While third-party services can help, if you do not set up such services, overwriting your files directly on the server means that they're overwritten forever. Reverting will require that you maintain some version control on the creator side.

Dynamic Sites

While making a bunch of static sites accessible to thousands of users was a huge invention and progress for the information age, it wasn't enough. As the amount of available content increased, the user experience became quite monotonous, impractical, and undiscoverable.

Dynamic sites were introduced in 1993 with the advent of the Common Gateway Interface (CGI). The CGI is a set of standards to define how information is exchanged between servers.

(CGI also, not to be confused with the other, more well-known Computer Generated Imagery, which is what makes Michael Bay movies pop. Fun fact: CGI's logo resembles the album cover for Pink Floyd's Dark Side of the Moon. But I disambiguate.)

In the barest terms, CGI allowed for servers to do more than just receive requests and respond to requests as input/output. CGIs allowed the server to process the request, which adds a layer of complexity to how websites are served to you via browser.

In a dynamic site:

When users access a site in their browser, the browser requests files from the server. The request could include a search query, a form submission, or even implicit data (like your geolocation).
Using the criteria set out by the CGI, the web server talks to another server (the application server) that processes all the inputs and makes a list of what it needs.
The application server will talk to another server, the database, to gather the information it needs, say, like, your order history or all the possible products. The application server translates this all into a language that the web server understands, and then sends it to the web server.
The web server sends the generated files to your browser.
Your browser renders the files and presents you with the website.

Dynamic sites opened up a whole world of the internet that was not possible before, customising the experience, introducing inextricable complexity in the process.

One could argue that applications and programs like Dreamweaver and FrontPage were the first static site generators that used a WYSIWYG editor. For brevity, I'm leaving that part of the history out.

Dynamic Site Examples

Dynamic sites are everything else. Any site that serves you a website from a database, an Application Programming Interface (API), or an experience based on input is a dynamic site. Common features on dynamic sites include shopping carts, search or content queries, location data, user data, and so on. Most "complex" sites tend to be dynamic; think Amazon, Facebook, Pinterest. (Most websites that are also a product also tend to be dynamic.)

Sites that are generated by CMSes like WordPress, Squarespace, and Shopify are also dynamic.

Dynamic Site Pros

Dynamic: As the name suggests, the power comes in generating content based on specific requests or data gathered (some of that data is gathered duplicitously and/or without consent, but a topic for another day).
Powerful: Dynamic sites allow for integration of CMSes, eCommerce platforms, and more complexity in general. Dynamic sites take the web from just a content storage platform, to a living, breathing information hub that can serve us content based on variables. That's pretty cool.
No-/Low-Code: The addition of CMSes and eCommerce platforms with dashboards means that code no longer becomes a requirement to create a site, lowering the barrier to entry. The cost of maintenance no longer requires code, but only familiarity with the editor interface (dashboard), which is quite a bit more economically viable to learn.
Out-of-Box Set-up: With platform integration, installing and launching a site becomes a lot faster. Products like Squarespace and Shopify boast the time to launch as a feature and earn their revenue through hosting the interface and your site.
Scalable : Adding more data or content already has a workflow and a place to store it (for example, you can import a thousand posts from another blogging platform or user data in a comma-separated values (CSV) file instead of manually entering it).
Consistent: As things like blog posts require an infrastructure, you can count each post appearing consistently based on the rules you set out.
Search Engine Optimisation (SEO)-Focused: Most CMSes are tailored to "business needs", which means that out of box, they tend to reveal ways to improve your SEO.
Version-Controlled : Most platforms integrate some sort of version controlling, so content can be reversed if an error is made.

Dynamic Site Cons 📌

Workarounds exist for all of these cons (and where appropriate, I've noted them) and some of them will be addressed in the SSG section, so hold your commenting horses.

Costly : Convenience comes at a price. While WordPress itself is free, themes and other add-ons can start to add up. Monthly paid services like Squarespace and Shopify can be cost-prohibitive to many people, and become exponentially costly as you want to add features for growth. Developers who specialise in these frameworks can also charge a premium as their skills tend to be niche.
Resource-Intensive: Every time a WordPress site is loaded, it has to call the server and ask for any scripts, plug-in libraries, etc. The time it takes to load these scripts can be long and require a lot of bandwidth.
Server Requirements : To run WordPress, special servers like Apache or NGINX are required. As with all things, there is a cost associated with this, which typically gets passed down the chain. To locally run a WordPress site (so that you're not making the edits live on the web), you need to do some manipulation to your machine, which can be confusing.
Slow : All of the inputs and dynamic calls result in having to wait for the server to do its job. We all know what that's like; when you're waiting for a colleague to finish their task before you can finish yours. Any delays in speed result in disengaged/unhappy users and thus, negatively impacted SEO measurements.
Cache-Difficult: Caching provides major benefits to sites. Caching basically stores a copy of the site somewhere else (whether that be on your computer in a temporary file) or on another server (like a content delivery network (CDN)). Doing so takes one load off of the main server you're accessing. However, caching becomes very complex when the server isn't quite sure even which HTML or images it should serve you because the variables are too vast (Are you logged in? Did you change a setting? Is there something in your cart? Did someone comment since you last logged in? Are you cute? How cute?)
Inaccessible:
- Heavy sites mean that users who rely on phone data (and pay per megabyte) are being economically taxed for accessing your site. In regions and contexts with systematically slower internet speeds, your users will likely bounce if your site is too slow. Remember, this is your fault for building a site maximised for 5G internet, not your user's inability to purchase an iPhone 14S.
- While a static site does not guarantee accessibility and you can make dynamic sites accessible, dynamic sites make out-of-box accessibility far more complex. A few static HTML pages will likely be fairly accessible as there's not much to them and HTML is fairly generous. However, the accessibility of a dynamic site becomes reliant on the accessibility of a platform on which it's built. The tools used to build the site (like the dash) need to be accessible as does the site itself. Any layer of complication increases the dimension of accessibility exponentially.
Insecure: Dynamic sites have to allow for input, which means that they open the doors for bugs and viruses. Something like 70-90% of WordPress sites are vulnerable to attacks. So, while they boast the statistic of being 2/3 of the web (why not just call it 69% tho), that means that over half of the web is insecure—like a middle school.
Instable : Unexpected spikes in traffic can overload the server with requests and break the site. We've seen this with news sites, high-heat commerce drops (think sneakerhead or video games), intensive retail periods like Black Friday/Cyber Monday, and other windows of extreme traffic.
Monotonous : Many sites can start to look the same (for example in Portland, there are at least a dozen coffee roasters who use the same Squarespace theme—those nuanced beans deserve better, dammit) as the out-of-box options tend to be limited.

Casting Extremes

As you can see, the landscape casts two extremes. On one end, you have something lean and agile, but fairly rigid. On the other end, you can have something brilliantly dynamic, but resource-intensive.

This is not a decision you should make based on what you, the developer, likes the most. It needs to be driven by myriad other factors, like who will ultimately be responsible for maintaining the site, what equitably provides as many users as possible with the bare need, and what will scale and maintain best over time. In short, we should be looking for resiliency over efficiency. Sometimes your hand will be forced; the decision for how to build a news or airline site, which has a lot of dynamic requirements, is a bit more obvious because you lack choice. You have to make it dynamic.

But what about a portfolio site for developer who wants a blog, but doesn't want to have to manually write all the HTML and copy and paste templates each time, nor do they want to feel limited by WordPress (or denying their abject fear of writing PHP and being denied entry into Developer Heaven)?

Or, what about a brochure site for a restaurant who wants to update their menu through a WYSIWYG but doesn't want to pay for the overhead of Squarespace?

Enter:

Static Site Generator-generated Sites* 📌

*It’s a little confusing because to be accurate means we have to be pedantic, hence the redundancy of Generator-generated. For purposes of clarity, this is how I differentiated the two; please note the difference:

SSGs: Static Site Generators. The thing that generates the site.

SSG sites: Static Site Generator-generated Sites. The sites that are generated.

Please know I thought very long and hard about this very trivial/non-trivial issue.

Static site generator-generated sites (SSG sites) provide a happy medium between the static sites and dynamic sites. Technically speaking, a site built from an SSG is a still static site.

SSG sites follow the same build process as static sites from above.

When users access a site in their browser, the browser requests files from the web server.
The web server gathers the files you need for the specific page you requested from a finite list of files that it has stored.
The web server sends the files to your browser. Your browser renders the files and presents you with the website.

Here there’s an added step that happens somewhat separately:

A. The person creating the site generates dynamic inputs, like markup language files, template files, data files, and assets.

B. The SSGs essentially take the actions that would happen on the server-side (like building a post into an HTML file) and perform them before the site is deployed. The SSG takes the dynamic inputs and compiles it into HTML, CSS, and JavaScript—these are the static files that get uploaded to the file server. Hence, the site becomes static.

The benefit of this added step is that it adds some of the developer/creator benefits of dynamic sites (like, writing content in Markdown and reusing templates) without as many of the dynamic cons (like, usually having to load an entire framework) while maintaining the pros of static sites. A Best of Both Worlds™ (BOBW) if you ask me.

To be explicit: Neither the user nor the server perceives, typically, the difference between a hard-coded static site and a SSG-generated site. To them, they're both static sites. SSGs improve the developer experience. I would even argue it's optimised to a certain niche of developer experience.

We have to admit that part of the rise of SSGs is that as developers, we are community-focused and want to be in-line with our peers. It would be dishonest, I think, to say that all of our motivation for anything (especially this) is ever purely user-motivated.

SSG Site Examples

New SSGs are popping up every day as this modern approach to tooling becomes more widely adopted. Popular static site generators (and their frameworks/languages) include: Hugo (Go), Gatsby, Next.js, React Static (React); NuxtJS (Vue.js); Middleman, Jekyll (Ruby); Sapper (Svelte); and my personal favourite, Eleventy (Node.js).

Examples of sites made on these SSGs on these can be found on each of those links. (See how the naming convention is confusing?!)

Aside: On JAMstack and Humans 📌

In the context of SSGs, you may have heard of JAMstack. JAMstack, which stands for JavaScript, APIs, and Markup, is not a three-tiered peanut butter and jelly sandwich. It is a movement, approach, workflow that was born out of developers wanting to maintain speed and security of static sites while adding some of the richness and tooling of dynamic sites. JAMstack also carries an ethic of performance-driven, low-cost, improved developer experience, and scalability. The hope, I think, is to bring many of the traditionally "back-end" capabilities like database manipulation into the realm of possibility for "front-end" developers.

How I like to think of the JAMstack approach is that everything in the world exists on a spectrum. While the line between static and dynamic was once more hard-drawn, the distinction between what constitutes static and dynamic is now more of a continuum. JAMstack further blurs that line or builds that bridge (depending on whether you think this is a good or bad thing).

Simultaneously, for us humans of the web, that means that the line between front-end and back-end development becomes less clear. Certain aspects of back-end development that were once inaccessible to front-end developers are becoming surfaced with movements like JAMstack and the tools they inspire.

Not all SSGs are part of the JAMstack. The JAMstack is not just about SSGs. (Read more on JAMstackWTF.)

SSG Site Pros 📌

Developer-Focused: Hand-coding websites is a pain in the Lance Bass. It's fun to be artisanal for a second, but once you get into dozens (hundreds, thousands) of pages, it becomes frustrating and confusing. On the dynamic side, manipulating WordPress and Squarespace to do all you know is possible can be frustrating (I know that the folks who work on these teams work very hard to improve dev experience as it's a weak spot in most dynamic site generators).
Separation of Concerns : SSG sites maintain the separation of visual presentation and content. You can continue to write new content as Markdown files without manually applying styling to it as you would with a hand-coded static site.
Reusable : Global changes to templates (e.g., blog post template) and components (e.g., navigation) are made by editing one file instead of many.
Metadata : One of the most powerful aspects of SSGs is that it surfaces the metadata: the title of the page, published date, site taxonomy, hero image, etc, can be defined and changed without touching the templates themselves, reinforcing the separation of concerns. Metadata is surfaced in something called front matter, which allows the content maintainer to add and customised data to the literal front of their file. (I'll talk more about this and show examples when we dive into Eleventy's structure in part II.)
Lean : As with a static site, the delivered files are what they are. It takes up less room on the internet, which is minimalist and aligns with our designer ways (rerolls turtleneck collar).
Fast: Lessening the number of server requests means your site will be faster, which improves your SEO and user experience, providing better access to more users.
Economic : Most SSGs are free to set up.
Asset Management: On static sites, asset management is largely manual; you might run individual photos and CSS files through some processes. On dynamic sites, image handling is automated and quite dialed in by way of plug-ins and platform-wide support. Most SSGs include some sort of process for assets, including compiling, transpiling, minifying, and bundling assets. SSGs provide build processes for anything from photo management (serving appropriately sized images) to CSS minification (rewriting your CSS into what the browser needs to read rather than what's optimal for developers to read).
Build Customisation: Most SSGs allow you to manipulate how the build process happens. So, if you want to see the site refresh live as you make edits, that's usually possible. If you want to check for specific linting processes, that's possible too.

SSG Site Cons

In addition to the cons from static sites, here are a few more SSG-specific limitations.

Complicated Setup : Atop needing to know the foundational HTML and CSS and some JS, you now need to also have an understanding of command-line interfaces (CLI) and package management to set up your environment. This is no small feat and creates a massive barrier to entry. Every SSG I've ever tried to set up has been confusing. I've learned that even the most competent developers can struggle with this initial step of the process.
Choice Overload : Modern development's embrace of SSGs means there are many SSG choices across many languages and language libraries. While this is generally a good thing, it can make it VERY confusing and intimidating if you don't already have a language loyalty. How do you pick which SSG when you don't know if you want to learn JS or Ruby or what?
Niche Skillset :
- While WordPress and Drupal developers tend to be more abundant, developers who are versed in using SSGs tend to be fewer (partly because the application of the technology is relatively new, comparatively). You could find yourself using an SSG without someone to update it, which is a risk.
- Some developers become developers of a specific SSG, like "Gatsby developers", which tethers their economic success to a specific framework. I personally think this can be risky. As each framework is nuanced, learning can pigeon-hole you if you're not careful (same problem as becoming a WordPress developer, for example).
Limited : While some possibilities are possible (and increasingly so by way of movements like JAMstack), adding user-generated content or real-time-influenced data is still not really possible. The more complex your desires, the more you're going to have to hack the SSG to do what you want. This increases barriers to entry and instability.
Slow Build Times: As you're building everything pre-deploy, you have to rebuild the entire website. As you may well know, waiting for a SSG to load all of its npm packages is time-consuming. On top of that, if you have a large blog or asset-intensive website, you will have to wait for it to build when you're developing. It's a buzz kill (but better our dev team than millions of users...right? RIGHT.).
Gatekept : Without a CMS, you have to know how to write code to publish content. Most SSGs require you to know some sort of templating language, at minimum, like Markdown.

Why Eleventy 📌

~~As a developer advocate for Eleventy**,~~ I favour Eleventy for most smaller projects because the way it was built aligns with my personal developer ethos. I do not like serving the user a bunch of unnecessary JavaScript to serve what will inevitably be static content.

Eleventy's mission seems to possess some similar biases to me. In the end, this is a huge factor in what we look for as developers, whether we admit it or not.

(**Also so the creator, Zach, doesn't get mad at me, Eleventy doesn't actually have developer advocates and is a community-contributed and -funded project. If you find Eleventy helpful and can, throw a few bucks at them!

Pros

Performance-First: Eleventy is very lean. It doesn't take 30 minutes to build my Eleventy site.
Community-Driven: As much as possible, I try to use tools that have a supportive community around them.
Independent: I try to support projects that don't fund and/or evangelise multi-billionaire companies (though I possess no judgment around this because I think we all gotta make a living).
Language Agnostic: While Eleventy's functionality is written in Node.js, the templating is very flexible, accepting Markdown, HTML, JS, Nunjucks, or any hot mess combination of all of them if you thrive in chaos (which you can see that I do if you look at my own website source code, thank you very much.)
Fast Build Times : I hate waiting for my site to build as a developer. If I wanted to wait for the internet, I'd get dial-up again. Jokes aside, build time and delay can be a major downside of sites on massive dynamic frameworks. Luckily, Eleventy is so lean and most of the sites I choose to build on Eleventy are too. (It's important to note that any SSG built atop a framework, like NuxtJS (Vue.js) or Gatsby (React) means that you'll have to wait for those frameworks to build, which can take time.)
Friendship : I consider Zach a friend. I like to support my friends and what they build.

Cons

Limited Tooling : As Eleventy is small and community-driven (without massive corporate backing), it doesn't have as much tooling support as, say Gatsby. Whereas Gatsby has some pretty cool/sophisticated image handler, handling images in Eleventy is somewhat bare-bones.
Sparse Documentation: Again, because it's small and community-funded and -maintained, the documentation is sparse. I get the sense that because Eleventy was initially marketed as an alternative to Jekyll, much of the documentation presumes Jekyll (reminder, it's another SSG) familiarity and competency. I found the barrier to entry quite high for me post-install, even though I have a fairly solid grasp on development and templating.
Limited Tutorials and Examples : Some community-generated tutorials exist for Eleventy, but not to the extent of some of the larger SSG communities.

To me, the pros outweigh the cons. Developers who work in and support Eleventy can help to improve the two cons. This is why I'm writing this series.

Next (Part II): Learn how to install Eleventy (and, all the things you need to to install in order to install Eleventy). Read Part II

Thank You

Thank you to Tierney Cyren and Heidi Olsen for their invaluable contributions as editors.

References

CSS Tricks: The Power of Serverless

Eleventy Docs

JAMstack.org

KeyCDN: Difference between Static and Dynamic Sites

Netlify: Top Ten Static Site Generators of 2017

Sitepoint: 7 Reasons to use a Static Site Generator

Bejamas: Wordpress Alternative: The Pros and Cons of Static Site Generators

Questions and Corrections

For questions, please reach out on Twitter! I can't promise to answer all your questions, but I'll try my best!

For corrections (typos, factual inaccuracies), please file a GitHub issue.

Monday Comms Tips

Tatiana Mac — Mon, 29 Apr 2019 00:00:00 +0000

I spent a lot of time in my inbox—I imagine many of you can relate. Over the years, I've gathered some helpful communication tips that I found improved my efficiency and happiness. Balancing my email time for me is an exercise in automating the right things, while maintaining the humanness of communications.

General

Designate work time/admin time based on your energy/brain power. Now, I have a bit of a privilege here as I work independently. I answer emails on Monday, when I struggle to focus on deep-thinking work. I do deep work mid-week. I take intro/mentorship calls later on the week when I'm wrapping deadlines.
I only respond to most bulky emails on Monday. I have to set this boundary, or else I find myself distracted all week long. I get stuck in the email cog.
You're not obligated to tell someone all your free times. Protect your you time.
Include pronouns in your email signature. If you're not sure of someone's pronouns, ask. Until you can ask, use gender neutral pronoun they/their/theirs and/or their name. Also be cognisant of accidentally outing people; always follow someone's lead and err on the side of uncertainty and asking 1:1 if you're unsure. If you mess up, apologise and fix.
Stop apologising for 'the delay.' We're perpetuating this idea that people must respond within 24 hours. What a strain on our mental health, and what an unfair expectation to set upon everyone. If you must acknowledge the perceived delay, reframe as gratitude or regret: "Thank you for bearing with me as I worked on my response." Or, "I regret it's taken me over a week to respond."
For bulkier emails, employ some information design. Create bulleted lists, bold action items. End emails with what you need to proceed.
Review your response to makes sure you answered all questions asked of you. So many extra emails are caused by not reviewing the original email fully.

Introductions

For intros, always ask permission of both parties before reaching out. Consent, always.
Provide context (websites/LinkedIn) and personal connection to encourage they do a bit of research and a clear reason you intro'd them.
Move the introducer to bcc: (with a note). Saves their inbox and lets them know you responded. As the introducer, remind folks "You can move me to bcc: when you respond.

Include your pronouns when introducing yourself. "Nice to meet you all. I'm Tatiana (I use she/they pronouns)." Set a precedence.

Scheduling

Offer times early in an email thread that will end there. I find that preemptively offering times avoids the empty back and forth of "when are you available?"
Include timezones. Use a tool like Spacetime to help you find amenable times without tying your brain into a knot.
To confirm a time, send a calendar invite. (I also frame language in earlier comms, so it's not an unexpected invite, which is jarring. Include time zones and make sure your calendar time zone is set.
Offer non-call alternatives when appropriate. When someone suggests a call as a default, and it doesn't feel necessary, I usually suggest another non-call way to solve it. For example, sometimes starting a document with initial ideas, or reading through something, etc, is what is warranted. I'll include a line like, "If we both still feel a call would be necessary after this, happy to schedule a call with an agenda to make the most of both our time." Despite being an ambivert, I find that calls drain me quite a bit. I also try to remind the other person that it's their time, too.

Scoping/Speaking

Save a list of questions and answers in your notes document. I find that I write the same questions and answers over and over, especially with scoping. Having a resource to copy and paste from is helpful.
When writing those answers, make sure you clearly highlight things you need to customise. It can be offputting to receive form responses.
Before asking a question, see if you can find it somewhere else, then confirm. For example, if you're about to ask someone their Twitter handle, try to do a preliminary search first.
Protect your expertise. Many people will reach out to ask for free advice and not immediately offer budget, even when they have it. I am always here to support mentorship and provide free advice to community members, especially newer and underrepresented folks. However, where I draw the line if if someone is making money off of my expertise. Phrasing I've found success with is, "I'm so flattered by this request! While I am happy to offer help to not-for-profit, community-focused events, I do ask for a fee when working with for-profit organisations like yours. The fee is..."
Maintain a spreadsheet with all your speaking events, with dates, honoraria, speaker bios, talk abstracts, and slide links. I promise it'll come in handy.
If you get asked the same questions over and over for speaking/scoping, consider making a speaker bio and/or Frequently Asked Questions page.

Why beginners should teach

Tatiana Mac — Wed, 17 Apr 2019 03:03:05 +0000

Beginners! I'd love to see more of you teach. You have tremendous value to offer. In our industry, we uphold and revere experts. I get it. Experts do sexy slick things in time lapses, have nice camera equipment, and great hair days.

Here are 10 reasons why I'd like to see more beginners teach; for yourself, for your future students, for your peers, and for our industry as a whole.

While you may be intimidated by how many tutorials already exist, you have to remember your uniqueness. People like different teaching styles, voices, EDM BG music selection. And, I'm gonna guess a lot of those tutorials are taught by experts, which leads to:
Beginners acutely feel the struggles of other beginners: confused with the onslaught of tools, terminology, and where to begin. The initial hurdle is the hardest. It's the place where quitting seems most appealing because there's an endless supply of things to learn.
Beginners want to see other beginners. Representation is a very important aspect of what we do: People get intimidated when they only see experts teaching high-level things. Seeing another beginner make mistakes on "basic things" then recover is very encouraging!
More beginners teaching will also show more beginner work! It's unrealistic to expect that your first will be on par with a practised expert whose done hundreds. That's okay! Share your "uglies," as they're probably not as bad as you think and are an impt part of the process!
More beginners will mean more forgiveness for mistakes. Our society is so fearful of mistakes and the gaslighting. Totally get it. Mistakes are icky. Peeps are dix. But mistakes are a necessary part of growth. So make 'em! Share what you learned from them! Fuck haters!
Internalising how to teach helps you organise how to learn: Where to start, where to focus, basic terms, anticipating your students' questions. For my Skillshare class, I knew I had to narrow the scope of all #a11y down to something compact enough to digest.
More beginner teachers means more people doing things they love, even if they're kinda bad at it at first. For me, it's drawing. My talented friends have been drawing since the womb. I'm old AF now. I have no time! So many of the hands I draw are uggo. WHO CARES. I HAD FUN!!!
Diversifying the levels will keep experts grounded and aware of newbie hurdles. Experts become super users of languages and tools; hearing beginner teachers will help to remind them of the initial struggles and help to cater their future, more advanced tutorials accordingly.
More beginners means more humility! We hide a lot of the "sausage making" from our peers, clients, the non-design world. But what if we were more okay accepting imperfect, in-progress, new things? Perhaps imposter syndrome would be less pervasive and there'd be less shame.
Most importantly, more beginners will inherently diversify and amplify a broader group of voices who haven't been "at the table" and advanced to experts—WoC, trans, disabled folks. Ignored and repressed voices.

I see you. You have value. Share with me your beginners teaching beginners channels and links! I'll save 'em and share. DM me on Twitter if you have questions on how to structure scripts, platforms to host, etc or just need to get out of your own head! You got this!!!

Maximising one-on-ones

Tatiana Mac — Tue, 14 Mar 2017 00:00:00 +0000

The creative industry, and the creatives who inhabit it, have a wealth of resources at our disposal.

Want to learn more about user behaviors? Thousands of blog posts by industry experts break down tested research around the smallest UI nuances. Not sure about the best way to texturise hair in Illustrator? There’s hundreds of YouTube videos on that. Widely available and affordable/Open Source design resources are one of the many great aspects of working and learning in this industry.

However, for all of the tools that exist to learn technical skills, we lack the tools to learn and discuss what creative leadership looks like. A handful of written resources do exist: Harvest Business Review and 99u, but on the by and large, creative leaders are left to learn (or not to learn) the skills to develop future design leaders. On occasion, I have enlightening discussions at events or hear a profound speakers on the subject but these experiences and articles are exceptions rather than the norm.

As creative leaders, we need to discuss the leadership aspects of our jobs more. Instead of learning from just our individual experiences, how can we cultivate a culture where we have more conversations around the work as it pertains to the people? What methodologies do we as creative leaders find most effective?

I am by no means asserting that I am a single-handed expert on creative leadership. Through this series, however, I do hope I can put what I’m doing to start this conversations with my peers.

One-on-ones

One-on-ones (or 1:1s) were something new to me when I started agency life. For those not familiar: A one-on-one is a standing meeting (typically weekly) for two people to regularly connect.

One-on-ones are intended to be regularly scheduled, closed-door conversations between managers and direct reports (but they can also extend to leadership or project peers). At their best, they provide a safe space to discuss goals, challenges, and feedback. At their worst, they can be viewed as a weekly rote update or worse, a standing calendar invite that does not happen at all.

Below are ways I’ve found to maximize my 1:1s as a manager to being an effective use of both parties’ time. I’m always adapting and hoping to find ways to adjust 1:1s to work for the individuals on my team.

1. Logistics are key: Set a weekly cadence and time allotment in a private place, then make sure it happens

Part of the efficacy of a 1:1 is holding it with regularity. Weekly seems to be a good cadence for my past teams (monthly or bimonthly makes sense for peripheral team members). It is consistent enough to make meaningful progress on projects without being overbearing.

The private place (whether that be digitally or physically) should be a no-brainer, but sometimes sensitive information about challenges with other team members, or personal details are discussed. It’s important that your team members feel comfortable. Setting the 1:1 in a closed-door setting will help facilitate that.

It’s easier for the “busier” person of the two to de-prioritize 1:1s. I try very hard to not cancel/move 1:1s. To me, this commitment is a manifestation of how important this individual is and how important their work is to our collective success.

If I do have to move or to cancel it, I try to communicate it early, take the initiative to reschedule/hold our next meeting, and apologize. I expect the same respect in return.

2. Ensure that it's a two-way conversation

As an ambivert, this is something I try to be extra mindful about: Give space for more introverted, quieter team members to share. Sometimes it takes time and awkward silence to happen, but it always will. If it doesn’t, you might not be asking the right questions…which leads to:

3. Ask open-ended questions

Forcing yourself out of the habit of asking yes/no questions will force your team member to prioritize the information they think is most meaningful and avoid rote-update type answers.

4. Adjust based on team members' communication styles and needs

Not every team member can or should be treated exactly the same. Some team members want to get down to business and not waste time with pleasantries. Other team members prefer to ease into business—and appreciate the discussion around weekends and life beyond work.

A tool we used at a previous job is the TTI Communication Assessment. Every team member takes a test that helps provide context for how they communicate and prefer others to communicate back. The entire team has access to one another’s profiles. I try to keep these preferences in mind to adjust how I speak to each employee.

5. Keep the big picture in mind

As the manager (especially if you’re a manager of managers) it’s important that you keep the priority and task clear. It is our job to ensure that the team member is making progress on larger quarterly and annual goals. If a team member is spending a lot of time on something that doesn’t align with their ultimate career trajectory goals, then it’s your job to redirect and re-prioritize to get them back on track.

6. Set clear directions then hold the person accountable with written documentation

I find discontent happens most often with team members when they have unclear directions or are not held consistently accountable (then, unexpectedly held accountable).

For each team member, we keep an shared Google Doc where I take ongoing notes during the 1:1. If we agree on an action item for either of us, it’s marked as such and we ensure we check in on those items during the following 1:1. Particularly, since those action items don’t usually pertain to hard deliverables, it holds us both accountable when having a difficult conversation or checking on back-burner tasks.

The 1:1 document is supremely helpful at the end of year review when it’s easy to forget what challenges and wins each team member has faced throughout the year. I use the 1:1 document to cite specific examples to support these growth plans.

7. Use 1:1s to provide critical and positive feedback in a timely manner

Lack of consistent feedback is a common challenge for employees (and warrants its own blog post). Studies consistently show that employees crave more feedback (both positive and productive) than they receive, and that employees who receive consistent feedback are more satisfied and engaged.

The 1:1 provides all of the groundwork for providing feedback: Private setting for the candid discussion, consistently held. I think the primary reason people avoid giving feedback is that it can feel awkward.

As the manager, if you provide feedback consistently (and elicit feedback yourself), it’s going to feel more normal to you and your team member to give and to receive feedback week over week.

Doing so in the 1:1 also reveals trends. If someone is consistently receiving feedback in the same areas and isn’t making improvement, you might need a plan in place or more active mediation. Alternatively, if someone received feedback a few times and made progress, that’s also good to call to attention.

What have you found successful in your 1:1s? I’d love to hear what methods you have found to be effective for you.